A1: macOS readiness: setup guide, cargo xtask mac-report, unix/macOS fixes

- docs/macos.md: step-by-step setup for a fresh Apple Silicon Mac (Xcode
  CLT, Homebrew, git, PHP, Composer, Node 22, pnpm, rustup, clone from
  Forgejo), the machine report, Gatekeeper notes, macOS differences and
  what Windows cannot check.
- cargo xtask mac-report: versions, the gate steps, the bundled-UI desktop
  build and a self-check over the control channel (project, file,
  Phpactor, hover, git.status, terminal, screenshot, quit); every step
  times out and runs in a lutra_proc group; one report.md to send back.
- Fixes: macOS native menu (system menus only; Cmd+W stays buffer.close,
  Cmd+Q runs app.quit), xcap screenshot region in points on macOS
  (Retina), login shell (-l, /bin/zsh fallback) and LANG for the
  terminal on macOS, PHP lookup in Homebrew/MacPorts dirs for Finder
  starts, case-insensitive LSP path mapping on macOS, rendezvous file
  mode re-set to 0600, CLI-started desktop in its own process group.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-31 14:47:45 +01:00
parent da58c83158
commit 1bf69ded55
18 changed files with 1795 additions and 36 deletions

View file

@ -106,13 +106,13 @@ impl PhpError {
}
/// Finds PHP and checks it: the `setting` (`php.executable`; empty means
/// look in `PATH`), resolved with [`locate`], then `php -v` with
/// [`PROBE_TIMEOUT`].
/// look in `PATH`, see [`search_path`]), resolved with [`locate`], then
/// `php -v` with [`PROBE_TIMEOUT`].
///
/// # Errors
/// [`PhpError`] saying what is missing or wrong.
pub fn detect(setting: &str) -> Result<Php, PhpError> {
let path = locate(setting, std::env::var_os("PATH"))?;
let path = locate(setting, search_path(std::env::var_os("PATH")))?;
let output = run_version(&path, PROBE_TIMEOUT)?;
let version =
parse_version(&output).ok_or_else(|| PhpError::NoVersion { path: path.clone() })?;
@ -122,6 +122,41 @@ pub fn detect(setting: &str) -> Result<Php, PhpError> {
Ok(Php { path, version })
}
/// Package manager folders searched after `PATH` on macOS: Homebrew on
/// Apple Silicon, Homebrew on Intel and MacPorts.
pub const MACOS_EXTRA_DIRS: [&str; 3] = ["/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin"];
/// The directories PHP is looked up in: `path_env`, and on macOS
/// [`MACOS_EXTRA_DIRS`] after it. An app started from the Finder or Dock
/// inherits only the system `PATH` (`/usr/bin:/bin:/usr/sbin:/sbin`), which
/// has no PHP since macOS 12, so Homebrew's PHP would not be found although
/// it works in Terminal.
pub fn search_path(path_env: Option<OsString>) -> Option<OsString> {
if !cfg!(target_os = "macos") {
return path_env;
}
with_extra_dirs(path_env, &MACOS_EXTRA_DIRS)
}
/// `path_env` with `extra` appended, skipping folders it lists already.
/// `None` only if both are empty; a `PATH` that cannot be joined again
/// (an entry with the separator in it) is returned unchanged.
fn with_extra_dirs(path_env: Option<OsString>, extra: &[&str]) -> Option<OsString> {
let mut dirs: Vec<PathBuf> = path_env
.as_ref()
.map(|p| std::env::split_paths(p).collect())
.unwrap_or_default();
for dir in extra {
if !dirs.iter().any(|d| d == Path::new(dir)) {
dirs.push(PathBuf::from(dir));
}
}
if dirs.is_empty() {
return path_env;
}
std::env::join_paths(dirs).ok().or(path_env)
}
/// Resolves the PHP executable.
///
/// - `setting` is the `php.executable` value, trimmed. A value with a path
@ -338,6 +373,23 @@ mod tests {
assert_eq!(locate(given.to_str().unwrap(), None).unwrap(), given);
}
#[test]
fn extra_dirs_come_after_path_once() {
let path = std::env::join_paths(["/usr/bin", "/opt/homebrew/bin"]).unwrap();
let joined = with_extra_dirs(Some(path), &["/opt/homebrew/bin", "/opt/local/bin"]);
let dirs: Vec<PathBuf> = std::env::split_paths(&joined.unwrap()).collect();
assert_eq!(
dirs,
["/usr/bin", "/opt/homebrew/bin", "/opt/local/bin"].map(PathBuf::from)
);
let only_extra = with_extra_dirs(None, &["/opt/local/bin"]).unwrap();
assert_eq!(only_extra, OsString::from("/opt/local/bin"));
assert_eq!(with_extra_dirs(None, &[]), None);
if !cfg!(target_os = "macos") {
assert_eq!(search_path(Some("x".into())), Some("x".into()));
}
}
#[test]
fn a_program_that_is_not_php_fails_cleanly() {
let dir = tempfile::tempdir().unwrap();