diff --git a/Cargo.lock b/Cargo.lock index c76a936..db349b4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -6549,7 +6549,9 @@ checksum = "e450f9b2ed1dff33c94c12589a87338689467b9c4f5d8a5710bd09a847d2c8a7" name = "xtask" version = "0.0.0" dependencies = [ + "lutra-proc", "serde_json", + "tempfile", "toml 1.1.8+spec-1.1.0", ] diff --git a/apps/lutra-cli/src/launch.rs b/apps/lutra-cli/src/launch.rs index 36ed239..3407746 100644 --- a/apps/lutra-cli/src/launch.rs +++ b/apps/lutra-cli/src/launch.rs @@ -56,7 +56,10 @@ pub fn find_desktop() -> Result { }) } -/// Starts `desktop` detached from this terminal and waits until it answers +/// Starts `desktop` detached from this terminal (Windows: a detached process +/// in a new process group; Unix: a new process group, so a Ctrl-C or +/// hangup aimed at the terminal's foreground group does not reach it) and +/// waits until it answers /// on the rendezvous file in `dir`. A desktop that exits successfully may /// have forwarded to an instance that started at the same time, so only a /// failed exit ends the wait early. @@ -77,6 +80,11 @@ pub fn start(desktop: &Path, dir: &Path) -> Result { const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200; command.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP); } + #[cfg(unix)] + { + use std::os::unix::process::CommandExt; + command.process_group(0); + } let mut child = command .spawn() .map_err(|e| format!("cannot start {}: {e}", desktop.display()))?; diff --git a/apps/lutra-desktop/src/main.rs b/apps/lutra-desktop/src/main.rs index 324917c..bf54809 100644 --- a/apps/lutra-desktop/src/main.rs +++ b/apps/lutra-desktop/src/main.rs @@ -18,6 +18,7 @@ mod args; mod datadir; mod host; mod instance; +mod menu; mod screenshot; use std::process::ExitCode; @@ -88,7 +89,7 @@ fn run(args: &args::Args) -> Result<(), String> { let setup_slot = slot.clone(); let initial_path = args.path.clone(); let focus_on_start = args.control.is_none(); - let app = tauri::Builder::default() + let app = menu::install(tauri::Builder::default()) .plugin(tauri_plugin_dialog::init()) .invoke_handler(tauri::generate_handler![ engine_execute, diff --git a/apps/lutra-desktop/src/menu.rs b/apps/lutra-desktop/src/menu.rs new file mode 100644 index 0000000..f5daa24 --- /dev/null +++ b/apps/lutra-desktop/src/menu.rs @@ -0,0 +1,102 @@ +//! The native menu bar on macOS. +//! +//! Lutra's own menu lives in the window (the frontend's app menu) on every +//! platform. macOS still needs a native menu bar: WKWebView gets Cut, Copy, +//! Paste, Select All, Undo and Redo through the Edit menu's key equivalents +//! (⌘X, ⌘C, ⌘V, ⌘A, ⌘Z, ⇧⌘Z) and does not handle those keys without it, and +//! users expect the app menu (About, Hide, Quit). +//! +//! Tauri's default macOS menu is not used because its key equivalents take +//! keys from Lutra's keymap before the page sees them: "Close Window" (⌘W) +//! would close the whole window, and so quit, where Lutra closes the editor +//! tab (`buffer.close`), and its "Quit" (⌘Q) would end the process without +//! Lutra's `app.quit` (closing terminals, shutting the language server down). +//! This menu leaves ⌘W to the page and routes Quit through `app.quit`. +//! +//! The menu is built with Tauri's cross-platform API, so it compiles and is +//! type-checked everywhere; [`install`] adds it on macOS only. + +use std::sync::Arc; + +use tauri::menu::{Menu, MenuEvent, MenuItem, PredefinedMenuItem, Submenu}; +use tauri::{AppHandle, Manager, Runtime}; + +use crate::host::Host; + +/// Menu item id of Quit; equal to the engine command it runs. +const QUIT_ID: &str = "app.quit"; + +/// Adds the native menu and its event handler to `builder` on macOS; +/// returns `builder` unchanged elsewhere, where the window has no native +/// menu bar. +pub fn install(builder: tauri::Builder) -> tauri::Builder { + if !cfg!(target_os = "macos") { + return builder; + } + builder.menu(build).on_menu_event(handle) +} + +/// Builds the menu bar: the app menu, Edit and Window. +/// +/// # Errors +/// Tauri's error if a menu or item cannot be created. +pub fn build(app: &AppHandle) -> tauri::Result> { + let quit = MenuItem::with_id(app, QUIT_ID, "Quit Lutra", true, Some("CmdOrCtrl+Q"))?; + let app_menu = Submenu::with_items( + app, + "Lutra", + true, + &[ + &PredefinedMenuItem::about(app, Some("About Lutra"), None)?, + &PredefinedMenuItem::separator(app)?, + &PredefinedMenuItem::services(app, None)?, + &PredefinedMenuItem::separator(app)?, + &PredefinedMenuItem::hide(app, None)?, + &PredefinedMenuItem::hide_others(app, None)?, + &PredefinedMenuItem::show_all(app, None)?, + &PredefinedMenuItem::separator(app)?, + &quit, + ], + )?; + let edit = Submenu::with_items( + app, + "Edit", + true, + &[ + &PredefinedMenuItem::undo(app, None)?, + &PredefinedMenuItem::redo(app, None)?, + &PredefinedMenuItem::separator(app)?, + &PredefinedMenuItem::cut(app, None)?, + &PredefinedMenuItem::copy(app, None)?, + &PredefinedMenuItem::paste(app, None)?, + &PredefinedMenuItem::select_all(app, None)?, + ], + )?; + let window = Submenu::with_items( + app, + "Window", + true, + &[ + &PredefinedMenuItem::minimize(app, None)?, + &PredefinedMenuItem::maximize(app, None)?, + &PredefinedMenuItem::separator(app)?, + &PredefinedMenuItem::fullscreen(app, None)?, + ], + )?; + Menu::with_items(app, &[&app_menu, &edit, &window]) +} + +/// Runs the engine command behind a custom menu item. Errors are ignored on +/// purpose: `app.quit` cannot fail, and without a host (before setup) the +/// app has nothing to shut down, so it exits directly. +fn handle(app: &AppHandle, event: MenuEvent) { + if event.id() != QUIT_ID { + return; + } + match app.try_state::>() { + Some(host) => { + let _ = host.run(QUIT_ID, serde_json::json!({})); + } + None => app.exit(0), + } +} diff --git a/apps/lutra-desktop/src/screenshot/region.rs b/apps/lutra-desktop/src/screenshot/region.rs index 37771cb..6ff09be 100644 --- a/apps/lutra-desktop/src/screenshot/region.rs +++ b/apps/lutra-desktop/src/screenshot/region.rs @@ -6,6 +6,15 @@ //! through Tauri and that region of its monitor is captured. The window is //! not focused or raised: anything covering it at that moment shows up in //! the image. +//! +//! Units: Tauri reports the window in physical pixels. `xcap` takes monitor +//! coordinates in physical pixels on Linux but in points (logical pixels) +//! on macOS, where a Retina display has two physical pixels per point; the +//! window's geometry is converted with its scale factor there +//! ([`window_rect`]). The image itself always comes back in physical pixels. +//! On macOS the first capture may ask for the Screen Recording permission +//! (System Settings ▸ Privacy & Security), granted to the app or terminal +//! that started Lutra. use std::io::Cursor; @@ -19,14 +28,9 @@ use xcap::image::ImageFormat; /// A message if the window's geometry or monitor cannot be read, the window /// is outside its monitor, or the capture or encoding fails. pub fn capture_png(window: &WebviewWindow) -> Result, String> { - let pos = window.inner_position().map_err(|e| e.to_string())?; - let size = window.inner_size().map_err(|e| e.to_string())?; - let centre_x = pos - .x - .saturating_add(i32::try_from(size.width / 2).unwrap_or(0)); - let centre_y = pos - .y - .saturating_add(i32::try_from(size.height / 2).unwrap_or(0)); + let (x, y, width, height) = window_rect(window)?; + let centre_x = x.saturating_add(i32::try_from(width / 2).unwrap_or(0)); + let centre_y = y.saturating_add(i32::try_from(height / 2).unwrap_or(0)); let monitor = Monitor::from_point(centre_x, centre_y) .map_err(|e| format!("cannot find the window's monitor: {e}"))?; let (mx, my) = ( @@ -38,10 +42,10 @@ pub fn capture_png(window: &WebviewWindow) -> Result, String> { monitor.height().map_err(|e| e.to_string())?, ); let region = clip( - pos.x.saturating_sub(mx), - pos.y.saturating_sub(my), - size.width, - size.height, + x.saturating_sub(mx), + y.saturating_sub(my), + width, + height, mw, mh, ) @@ -56,6 +60,40 @@ pub fn capture_png(window: &WebviewWindow) -> Result, String> { Ok(png.into_inner()) } +/// The window's client area as `(x, y, width, height)` in the units `xcap` +/// uses for monitors on this platform (see the module docs). +/// +/// # Errors +/// A message if Tauri cannot report the geometry or the scale factor. +fn window_rect(window: &WebviewWindow) -> Result<(i32, i32, u32, u32), String> { + let pos = window.inner_position().map_err(|e| e.to_string())?; + let size = window.inner_size().map_err(|e| e.to_string())?; + if cfg!(target_os = "macos") { + let scale = window.scale_factor().map_err(|e| e.to_string())?; + Ok(to_points(pos.x, pos.y, size.width, size.height, scale)) + } else { + Ok((pos.x, pos.y, size.width, size.height)) + } +} + +/// Converts a rectangle from physical pixels to points for a display with +/// `scale` physical pixels per point. A scale that is not a positive finite +/// number is treated as 1. +fn to_points(x: i32, y: i32, w: u32, h: u32, scale: f64) -> (i32, i32, u32, u32) { + let scale = if scale.is_finite() && scale > 0.0 { + scale + } else { + 1.0 + }; + let point = |v: f64| (v / scale).round(); + ( + point(f64::from(x)) as i32, + point(f64::from(y)) as i32, + point(f64::from(w)) as u32, + point(f64::from(h)) as u32, + ) +} + /// Clips a rectangle given relative to a monitor's origin to the monitor's /// bounds, returning `(x, y, width, height)` or `None` if nothing is left. fn clip(x: i32, y: i32, w: u32, h: u32, mw: u32, mh: u32) -> Option<(u32, u32, u32, u32)> { @@ -76,7 +114,15 @@ fn clip(x: i32, y: i32, w: u32, h: u32, mw: u32, mh: u32) -> Option<(u32, u32, u #[cfg(test)] mod tests { - use super::clip; + use super::{clip, to_points}; + + #[test] + fn converts_physical_pixels_to_points() { + assert_eq!(to_points(200, 100, 2560, 1600, 2.0), (100, 50, 1280, 800)); + assert_eq!(to_points(-300, 0, 99, 1, 1.5), (-200, 0, 66, 1)); + assert_eq!(to_points(10, 20, 30, 40, 0.0), (10, 20, 30, 40)); + assert_eq!(to_points(10, 20, 30, 40, f64::NAN), (10, 20, 30, 40)); + } #[test] fn clips_to_the_monitor() { diff --git a/crates/control/src/rendezvous.rs b/crates/control/src/rendezvous.rs index 134c5c6..d980be4 100644 --- a/crates/control/src/rendezvous.rs +++ b/crates/control/src/rendezvous.rs @@ -191,7 +191,9 @@ pub fn write(dir: &Path, instance: &Instance) -> io::Result<()> { } /// Creates `path` readable and writable by the owner only and writes -/// `bytes` to it. +/// `bytes` to it. On Unix the mode is set again after opening, because +/// `mode(0o600)` only applies when the file is created, and a stale +/// temporary file (same process id after a crash) keeps its old mode. /// /// # Errors /// If the file cannot be created or written. @@ -204,6 +206,11 @@ fn write_private(path: &Path, bytes: &[u8]) -> io::Result<()> { options.mode(0o600); } let mut file = options.open(path)?; + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + file.set_permissions(fs::Permissions::from_mode(0o600))?; + } file.write_all(bytes)?; file.sync_all() } diff --git a/crates/engine/src/cmd/lsp_nav.rs b/crates/engine/src/cmd/lsp_nav.rs index 36fe76e..d2cc829 100644 --- a/crates/engine/src/cmd/lsp_nav.rs +++ b/crates/engine/src/cmd/lsp_nav.rs @@ -291,8 +291,8 @@ pub fn locations(state: &State, root: &Path, value: &Value) -> Vec } /// `path` (absolute, from the server) relative to the project, or `None` -/// outside it. Windows paths compare without regard to case, as the file -/// system does, and `..` never escapes. A path that resolves through a +/// outside it. Windows and macOS paths compare without regard to case, as +/// their default file systems (NTFS, APFS) do, and `..` never escapes. A path that resolves through a /// symbolic link to a place outside the project counts as outside. pub fn project_relative(state: &State, root: &Path, path: &Path) -> Option { let rel = match state @@ -301,7 +301,7 @@ pub fn project_relative(state: &State, root: &Path, path: &Path) -> Option rel, - None => windows_relative(root, path)?, + None => case_insensitive_relative(root, path)?, }; if rel.components().any(|c| !matches!(c, Component::Normal(_))) { return None; @@ -316,9 +316,10 @@ pub fn project_relative(state: &State, root: &Path, path: &Path) -> Option Option { - if !cfg!(windows) { +/// The case-insensitive fallback of [`project_relative`] on Windows and +/// macOS. +fn case_insensitive_relative(root: &Path, path: &Path) -> Option { + if !cfg!(any(windows, target_os = "macos")) { return None; } let root_text = root.to_str()?.trim_end_matches(['\\', '/']); diff --git a/crates/engine/src/cmd/terminal.rs b/crates/engine/src/cmd/terminal.rs index 6561a1e..ee69dce 100644 --- a/crates/engine/src/cmd/terminal.rs +++ b/crates/engine/src/cmd/terminal.rs @@ -152,7 +152,7 @@ impl Command for Create { label: "New Terminal", menu_path: None, default_shortcut: None, - params: "{ cwd? (project-relative or absolute directory, default the project root), shell? (program name or path; default pwsh, then powershell, then cmd on Windows, $SHELL or /bin/sh elsewhere), cols, rows (1..=1000) }; returns { terminalId }, then events terminalOutput { terminalId, data } and terminalExited { terminalId, code }; at most 16 terminals", + params: "{ cwd? (project-relative or absolute directory, default the project root), shell? (program name or path; default pwsh, then powershell, then cmd on Windows, the login shell $SHELL -l (else /bin/zsh) on macOS, $SHELL or /bin/sh elsewhere), cols, rows (1..=1000) }; returns { terminalId }, then events terminalOutput { terminalId, data } and terminalExited { terminalId, code }; at most 16 terminals", } } diff --git a/crates/engine/src/lsp/mod.rs b/crates/engine/src/lsp/mod.rs index 4805dde..75438b7 100644 --- a/crates/engine/src/lsp/mod.rs +++ b/crates/engine/src/lsp/mod.rs @@ -971,13 +971,14 @@ fn clear_diagnostics(state: &mut State) { } } -/// `path` relative to `root`; `None` outside it. Windows paths compare -/// without regard to case, as the file system does. +/// `path` relative to `root`; `None` outside it. Windows and macOS paths +/// compare without regard to case, as their default file systems (NTFS, +/// APFS) do. fn relative(root: &Path, path: &Path) -> Option { if let Ok(rel) = path.strip_prefix(root) { return Some(rel.to_path_buf()); } - if !cfg!(windows) { + if !cfg!(any(windows, target_os = "macos")) { return None; } let root_text = root.to_str()?.trim_end_matches(['\\', '/']); @@ -1119,6 +1120,13 @@ mod tests { Some(PathBuf::from("b.php")) ); } + if cfg!(target_os = "macos") { + assert_eq!( + relative(&root, Path::new("/WORK/Demo/b.php")), + Some(PathBuf::from("b.php")) + ); + assert_eq!(relative(&root, Path::new("/WORK/Demo2/b.php")), None); + } } #[test] diff --git a/crates/lsp/src/toolchain/php.rs b/crates/lsp/src/toolchain/php.rs index 929051b..ba9c746 100644 --- a/crates/lsp/src/toolchain/php.rs +++ b/crates/lsp/src/toolchain/php.rs @@ -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 { - 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 { 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) -> Option { + 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, extra: &[&str]) -> Option { + let mut dirs: Vec = 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 = 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(); diff --git a/crates/terminal/src/session.rs b/crates/terminal/src/session.rs index c85ba52..cee766d 100644 --- a/crates/terminal/src/session.rs +++ b/crates/terminal/src/session.rs @@ -160,6 +160,22 @@ fn pty_size(cols: u16, rows: u16) -> Result { }) } +/// Whether the shell needs `LANG=en_US.UTF-8`: on macOS only, when neither +/// Lutra's environment nor `extra` sets `LANG`, `LC_ALL` or `LC_CTYPE`. +/// An app started from the Finder or Dock gets no locale, and without one +/// zsh and most tools treat non-ASCII text (umlauts in file names and +/// output) as unknown bytes; Terminal.app sets `LANG` the same way. +fn needs_utf8_locale(extra: &[(OsString, OsString)]) -> bool { + const LOCALE_VARS: [&str; 3] = ["LANG", "LC_ALL", "LC_CTYPE"]; + cfg!(target_os = "macos") + && LOCALE_VARS + .iter() + .all(|name| std::env::var_os(name).is_none_or(|v| v.is_empty())) + && !extra + .iter() + .any(|(key, _)| LOCALE_VARS.iter().any(|name| key == name)) +} + /// A spawn error from any displayable cause. fn spawn_error(e: impl std::fmt::Display) -> TerminalError { TerminalError::Spawn(e.to_string()) @@ -188,6 +204,9 @@ impl Session { cmd.env("TERM", "xterm-256color"); cmd.env("COLORTERM", "truecolor"); cmd.env("TERM_PROGRAM", "Lutra"); + if needs_utf8_locale(&options.env) { + cmd.env("LANG", "en_US.UTF-8"); + } for (key, value) in &options.env { cmd.env(key, value); } diff --git a/crates/terminal/src/shell.rs b/crates/terminal/src/shell.rs index 2366d1a..1a0c8fb 100644 --- a/crates/terminal/src/shell.rs +++ b/crates/terminal/src/shell.rs @@ -27,7 +27,13 @@ impl Shell { /// - **Windows:** `pwsh.exe` (PowerShell 7) from `PATH`, else /// `powershell.exe` (Windows PowerShell), else `%COMSPEC%`, else /// `cmd.exe`. PowerShell starts with `-NoLogo`. -/// - **Unix:** `$SHELL`, else `/bin/sh`. +/// - **macOS:** `$SHELL`, else `/bin/zsh` (the default login shell since +/// macOS 10.15), else `/bin/sh`, started as a login shell (`-l`) the way +/// Terminal.app does. A login shell reads `~/.zprofile`, where Homebrew +/// puts `/opt/homebrew/bin` on the `PATH`; without it, PHP and Composer +/// from Homebrew are missing in a Lutra started from the Finder or Dock, +/// which inherits only the system `PATH`. +/// - **Other Unix:** `$SHELL`, else `/bin/sh`. pub fn default_shell() -> Shell { if cfg!(windows) { for name in ["pwsh.exe", "powershell.exe"] { @@ -46,6 +52,15 @@ pub fn default_shell() -> Shell { let shell = std::env::var_os("SHELL") .filter(|s| !s.is_empty()) .map(PathBuf::from); + if cfg!(target_os = "macos") { + let program = shell + .or_else(|| Some(PathBuf::from("/bin/zsh")).filter(|p| p.is_file())) + .unwrap_or_else(|| PathBuf::from("/bin/sh")); + return Shell { + program, + args: vec![OsString::from("-l")], + }; + } Shell::new(shell.unwrap_or_else(|| PathBuf::from("/bin/sh"))) } @@ -101,6 +116,12 @@ mod tests { assert!(found, "{shell:?}"); } + #[cfg(target_os = "macos")] + #[test] + fn macos_starts_a_login_shell() { + assert_eq!(default_shell().args, vec![OsString::from("-l")]); + } + #[test] fn finds_programs_in_path() { let name = if cfg!(windows) { "cmd" } else { "sh" }; diff --git a/docs/development.md b/docs/development.md index b8686dc..2664558 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # Development -> **Status:** draft · **Last updated:** 2026-10-27 +> **Status:** draft · **Last updated:** 2026-10-31 ## Prerequisites @@ -8,6 +8,7 @@ - Node.js 22.12 or newer (Vite 8 needs it) and pnpm 10 - Tauri 2 system prerequisites for your platform (WebView2 on Windows, WebKitGTK on Linux) - Optional: Phpactor on the PATH for language features, PHP 8.2+ and Composer for reference projects +- macOS: a step-by-step setup for a fresh Apple Silicon Mac is in [`macos.md`](macos.md) ## Everyday commands @@ -16,8 +17,11 @@ cargo xtask dev # run the app in development mode cargo xtask dev -- --control 7979 . # with the JSON control channel cargo xtask ci # the full quality gate, run before every commit cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/ +cargo xtask mac-report # gate, build and an app self-check, written to target/mac-report/report.md ``` +`mac-report` is made for checking a machine the developers cannot reach (the Mac, see [`macos.md`](macos.md)) but runs everywhere. Every step has a timeout; `--skip-gate` leaves out the gate, `--port` picks the control port (default 7971). + ## Data directories A `--control PORT` instance keeps its settings, recovery journal and webview data in `/lutra-control//`, never in your own data directory, so a dev or agent instance cannot change your settings or restore your journal. `--data-dir DIR` or `LUTRA_DATA_DIR=DIR` pick another directory, for any instance: @@ -56,6 +60,7 @@ No inline comments. Doc comment blocks above modules, functions, types and field | Date | Change | Summary | |---|---|---| +| 2026-10-31 | minor | A1: `cargo xtask mac-report`, link to the macOS setup | | 2026-10-27 | minor | F3: data directories, build directories inside the repository, parallel builds, deleting `ui/node_modules` | | 2026-10-27 | minor | Unfocused `--control` windows and the screenshot focus check (F2) | | 2026-10-25 | minor | Isolated data directory for `--control` instances (H6) | diff --git a/docs/gaps.md b/docs/gaps.md index be879ce..61c62ec 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -10,7 +10,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t | 2026-10-30 | minor | New item: `--control` start can take the foreground; screenshot timeouts explained (F2b) | | G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) | | G2 | Editor core: ~~engine buffers, save~~ (M1.3), ~~editor UI with tabs, undo, multi-caret~~ (M1.6, CodeMirror basics), ~~recovery journal~~ (M1.7), tab management (preview, pin, split, close others, reopen), conflict UI for files changed on disk, ~~autosave~~ (M3.10), local history | M1 | ~14 h | -| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, ~~showing truncated listings~~ (M1.13), ~~error notifications for the folder picker~~ (M1.12), ~~tabs~~ (M1.6), ~~command palette~~ (M1.8: commands only, global keymap, UI commands over the control channel); ~~settings~~ (backend: M1.9a; dialog with search: M1.9b; string and path controls: H4), ~~theme switching~~ (M1.10: light/dark, live, system mode; picker in the dialog, M1.9b), ~~main menu~~ (M3.9: hamburger dropdown from `menuPath`s; native macOS menu bar and display modes open) | M1 | ~24 h | +| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, ~~showing truncated listings~~ (M1.13), ~~error notifications for the folder picker~~ (M1.12), ~~tabs~~ (M1.6), ~~command palette~~ (M1.8: commands only, global keymap, UI commands over the control channel); ~~settings~~ (backend: M1.9a; dialog with search: M1.9b; string and path controls: H4), ~~theme switching~~ (M1.10: light/dark, live, system mode; picker in the dialog, M1.9b), ~~main menu~~ (M3.9: hamburger dropdown from `menuPath`s; native macOS menu bar: A1 adds the system menus (Lutra, Edit, Window; ⌘W and ⌘Q stay Lutra's), mirroring Lutra's own menus natively and display modes open) | M1 | ~24 h | | G4 | Syntax and structure: tree-sitter PHP, ~~Lezer highlighting~~ (M2.2: PHP with embedded HTML plus HTML, CSS, JS/TS, JSON, YAML, Markdown; `--lt-syntax-*` tokens; `editor.reveal`), ~~file structure~~ (M2.7: Structure tool window, `syntax.outline`), semantic highlighting, folding in the editor | M2 | ~8 h | | G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h | | G6 | Language server: completion, definition, hover, rename via Phpactor (~~PHP detection and Phpactor download~~, M3.1; ~~engine wiring and diagnostics~~, M3.3; ~~completion, hover, signature help~~, M3.4; ~~definition, references, rename~~, M3.5) | M3 | ~15 h | @@ -47,7 +47,7 @@ G5 progress: M2.3 landed the find-in-files backend: `crates/search` (parallel wa Known smaller items from M0: - The CI workflow has never run: the repository has no remote until the owner decides on hosting. -- ~~`ui.screenshot` captures the screen region of the window and focuses it~~ (F2, C6: WebView2 `CapturePreview` on Windows, never focuses). macOS and Linux still capture the screen region (without focus), so covering windows appear there. +- ~~`ui.screenshot` captures the screen region of the window and focuses it~~ (F2, C6: WebView2 `CapturePreview` on Windows, never focuses). macOS and Linux still capture the screen region (without focus), so covering windows appear there. A1 (C7) converts the region to points on macOS, which `xcap` expects there (it was off by the Retina scale); WKWebView's own snapshot would still be better. - A `--control` instance started from the foreground app's process tree (an agent run from Claude) became the foreground window about 1 s after start 4 times on 2026-10-29/30, although window and webview are built with `focused(false)`. In 20 starts on 2026-10-30 (8 traced with an activation hook) it never happened, and nothing on Lutra's thread requested activation, so the cause is outside Lutra's code and intermittent. The ignored test `screenshot_focus` guards it; the probe is in the C6 notes. Screenshots themselves do not take the foreground. A hidden page (locked session, display asleep) gives WebView2 no frames to capture; the error now says so. - `cargo xtask fixtures` needs Composer, which the M0 machine does not have. @@ -57,6 +57,7 @@ G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framin | Date | Change | Summary | |---|---|---| +| 2026-10-31 | patch | A1: macOS system menus (G3), Retina region for the macOS screenshot fallback | | 2026-10-30 | patch | C6 review: the foreground-grab item is not reproduced in 20 starts; cause outside Lutra | | 2026-10-28 | patch | G8: log and file history (M4.6) | | 2026-10-28 | minor | G8 shrunk: remotes (M4.10) | diff --git a/docs/macos.md b/docs/macos.md new file mode 100644 index 0000000..ebbdf0b --- /dev/null +++ b/docs/macos.md @@ -0,0 +1,221 @@ +# macOS + +> **Status:** draft, written without a Mac, not yet run on one · **Last updated:** 2026-10-31 + +How to set up a fresh Apple Silicon Mac (M1 or newer, macOS 14 Sonoma or newer) to build, test and run Lutra from source, and how to send a machine report back to the developers. Follow the steps in order and type the commands exactly as shown; each one is a single line for the Terminal. + +Lutra is not signed or notarised yet, and there is no installer (DMG). You build it yourself, which is fine for the alpha: a program you build on your own Mac is not quarantined, so Gatekeeper does not block it (see [Gatekeeper](#gatekeeper-and-code-signing)). + +## 1. Open Terminal + +Press ⌘ Space, type `Terminal`, press Return. Everything below happens in that window. The shell is zsh, the macOS default. + +## 2. Xcode Command Line Tools + +The compiler and linker that Rust uses, plus Apple's `git`. + +```sh +xcode-select --install +``` + +A window asks to install the tools: click **Install** and accept the licence. It takes a few minutes. Check it: + +```sh +xcode-select -p +``` + +It prints `/Library/Developer/CommandLineTools` (or a path inside Xcode.app if you have full Xcode; that works too). If it says the tools are already installed, go on. + +## 3. Homebrew + +The package manager for PHP, Node and the rest. Install it with the command from [brew.sh](https://brew.sh): + +```sh +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +It asks for your Mac password (typing shows nothing; that is normal). At the end it prints **Next steps** with two commands that put Homebrew on your `PATH`. On Apple Silicon they are: + +```sh +echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile +``` + +```sh +eval "$(/opt/homebrew/bin/brew shellenv)" +``` + +Check it: + +```sh +brew --version +``` + +## 4. Git, PHP, Composer, Node and pnpm + +```sh +brew install git php composer node@22 pnpm +``` + +`node@22` is "keg-only", so put it on the `PATH` yourself: + +```sh +echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zprofile +``` + +Then **close the Terminal window and open a new one**, so the new `PATH` applies. Check the versions: + +```sh +git --version && php -v && composer --version && node -v && pnpm -v +``` + +You need git 2.30 or newer, PHP 8.2 or newer, Node 22.12 or newer and pnpm 10. Homebrew's `git` is newer than Apple's; both work. + +## 5. Rust + +Install rustup, the Rust installer, from [rustup.rs](https://rustup.rs): + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +Press Return to accept the default installation. Then load it into this window: + +```sh +. "$HOME/.cargo/env" +``` + +Check it: + +```sh +rustc -V && cargo -V +``` + +Optional, for the licence check of the gate (the report skips it without): + +```sh +cargo install cargo-deny --locked +``` + +This compiles for a few minutes. + +## 6. Get the code + +Lutra lives on Daniel's Forgejo server and is cloned over SSH. If this Mac has no SSH key for it yet, create one and add the public key to your Forgejo account (Settings ▸ SSH / GPG Keys ▸ Add Key): + +```sh +ssh-keygen -t ed25519 -C "lutra-mac" +``` + +Press Return three times (default file, no passphrase, or set one if you like). Show the public key to copy it: + +```sh +cat ~/.ssh/id_ed25519.pub +``` + +Then clone into a folder of your choice, for example `~/Projekte`: + +```sh +mkdir -p ~/Projekte && cd ~/Projekte +``` + +```sh +git clone ssh://git@git.daniel-diekert.com:2222/daniel/Lutra.git lutra +``` + +The first connection asks whether to trust the server's host key: type `yes`. + +```sh +cd lutra +``` + +## 7. The machine report + +One command checks the Mac end to end and writes one file to send back: + +```sh +cargo xtask mac-report +``` + +It runs, with a timeout on every step so it never hangs: + +1. the versions of macOS, the Command Line Tools, Rust, Node, pnpm, git, PHP and Composer; +2. the quality gate: `cargo fmt`, `cargo clippy`, `cargo test`, the project checks, `cargo deny` (skipped without cargo-deny) and the frontend's lint, typecheck and tests; +3. the frontend build and a build of the desktop app with the UI bundled in; +4. one start of the app with a fresh, separate data folder and the control channel on port 7971, and a self-check through it: open a small demo project, open a PHP file, wait for Phpactor (the language server is downloaded on first use, which needs the internet), a hover, `git.status`, a terminal that runs a command, a screenshot, and quitting the app. + +The first run takes a while (about 20–40 minutes, mostly compiling); later runs are much faster. The Lutra window opens for a minute near the end, in the background; leave it alone and it closes itself. + +When it finishes it prints where the report is: + +``` +mac-report: report written to /Users//Projekte/lutra/target/mac-report/report.md +``` + +**Send back `target/mac-report/report.md`** and `target/mac-report/screenshot.png`. If a step failed, also zip and send the `target/mac-report/logs` folder. A failure does not stop the report; failed steps are listed with their error text. + +Options: + +- `cargo xtask mac-report --skip-gate`: only the build and the app self-check (about 10 minutes the first time). Useful after a fix to the app. +- `--port 7972`: another control port, if 7971 is taken. +- `--out DIR`: write the report somewhere else. + +### Screen Recording permission + +The screenshot step captures the Lutra window from the screen. The first time, macOS may ask whether **Terminal** may record the screen. Click **Open System Settings** and turn on Terminal under Privacy & Security ▸ Screen & System Audio Recording, then run the report again. If you decline, only the screenshot step fails. + +## 8. Running Lutra by hand + +For the alpha checklist, start the app from the repository folder: + +```sh +cargo xtask dev +``` + +The first time this asks for the Tauri CLI; install it with `cargo install tauri-cli --locked`. Or run the self-contained build the report made: + +```sh +target/debug/lutra-desktop ~/Projekte/some-php-project +``` + +## Gatekeeper and code signing + +- **Built on this Mac:** files you compile yourself (with `cargo`) carry no quarantine attribute, and the Apple Silicon linker signs them ad hoc automatically, so they run without any Gatekeeper prompt. That covers everything in this guide. +- **Copied from elsewhere:** a Lutra binary downloaded with a browser, AirDrop or a chat app is quarantined, and because it is not notarised, macOS refuses to open it ("cannot be opened because Apple cannot check it for malicious software"). Only for a build you trust, remove the quarantine attribute: + + ```sh + xattr -dr com.apple.quarantine /path/to/lutra-desktop + ``` + + Or open it once with a right click ▸ Open (on macOS 15 and later: try to open it, then System Settings ▸ Privacy & Security ▸ Open Anyway). +- **Phpactor:** Lutra downloads the Phpactor PHAR itself and checks its SHA-256; files that Lutra writes are not quarantined, and PHP runs the PHAR, so Gatekeeper is not involved. +- Real signing and notarisation need an Apple Developer ID and the final app identifier (open owner decision O2); they come with the installers, after the alpha. + +## What is different on macOS + +- **Menu bar.** Lutra's own menu is inside the window, as on Windows. The macOS menu bar has the Lutra menu (About, Hide, Quit), Edit (Undo, Redo, Cut, Copy, Paste, Select All: macOS web views need these for the clipboard keys) and Window (Minimize, Zoom, Full Screen). ⌘W closes the editor tab, not the window, and ⌘Q quits through Lutra's own Quit (terminals closed, the language server shut down). +- **Shortcuts.** `Mod` in Lutra's keymap is ⌘ on macOS and Ctrl elsewhere. +- **Terminal.** The integrated terminal starts your login shell (`$SHELL`, normally zsh) with `-l`, as Terminal.app does, so `~/.zprofile` runs and Homebrew's PHP and Composer are on the `PATH` even when Lutra was started from the Finder or Dock. Without a locale in the environment it sets `LANG=en_US.UTF-8`. +- **PHP.** Lutra finds PHP on the `PATH` and, after it, in `/opt/homebrew/bin`, `/usr/local/bin` and `/opt/local/bin`, because an app started from the Finder only gets the system `PATH`. The setting `php.executable` overrides both. +- **Data.** Settings, the recovery journal and the downloaded Phpactor live in `~/Library/Application Support/dev.lutra.desktop/`. An instance started with `--control` or `--data-dir` (as the report does) uses its own folder and shares only the Phpactor download. +- **File names.** The default APFS volume ignores case, like Windows, so paths the language server reports are matched to project files without regard to case. + +## What was checked without a Mac + +The developers have no Mac. On 2026-10-31 (A1), `cargo check --all-targets --target aarch64-apple-darwin` ran on Windows for every crate: + +- **passed:** `lutra-text`, `lutra-proc` (its Unix process groups and watchdog), `lutra-vfs`, `lutra-terminal` (PTY, default shell, locale), `lutra-vcs`, `xtask` (`mac-report`); +- **cannot be checked from Windows:** every crate that depends on a C build script needs a C compiler and the macOS SDK: `ring` (TLS for the Phpactor download) for `lutra-search`, `lutra-lsp`, `lutra-index`, `lutra-control`, `lutra-engine`, `lutra-mcp` and `lutra-cli`; `tree-sitter` for `lutra-syntax`; `objc2-exception-helper` for `lutra-desktop`. Most of their macOS-specific code uses `cfg!(target_os = "macos")` inside ordinary code, so the Windows build type-checks it anyway; only the `xcap` screenshot module (`#[cfg(not(windows))]`) is compiled on the Mac alone. +- `cargo xtask mac-report --skip-gate` ran green on Windows (build, app start, project, file, Phpactor, hover, git, terminal, screenshot, quit). + +These can only be checked on the Mac itself, which is what the report does: + +- everything that builds C or Objective-C code (the desktop app with Tauri, WKWebView and `xcap`; the terminal's PTY layer links against the system); +- the Unix process groups and the `/bin/sh` watchdog of `lutra_proc` at run time (they are the same as on Linux, where the tests passed earlier); +- the PTY, the login shell and the screenshot on a Retina display; +- the menu bar and its keys. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-31 | major | A1: initial guide (setup, `cargo xtask mac-report`, Gatekeeper, macOS differences, what Windows cannot check) | diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index ac1f237..4f4ed3d 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "xtask" -description = "Project automation: ci, layers, assets, cleanroom, dev, fixtures" +description = "Project automation: ci, layers, assets, cleanroom, dev, fixtures, mac-report" version.workspace = true edition.workspace = true rust-version.workspace = true @@ -12,8 +12,12 @@ publish.workspace = true layer = "tool" [dependencies] +lutra-proc.workspace = true serde_json = "1.0.154" toml = "1.1.8" +[dev-dependencies] +tempfile.workspace = true + [lints] workspace = true diff --git a/xtask/src/macreport.rs b/xtask/src/macreport.rs new file mode 100644 index 0000000..f0b192b --- /dev/null +++ b/xtask/src/macreport.rs @@ -0,0 +1,1253 @@ +//! `mac-report`: one command that checks a machine end to end and writes a +//! single report file to send back. +//! +//! Made for the macOS alpha check (the developers have no Mac), but it runs +//! on every platform, so it can be tried out where it is written. In order: +//! +//! 1. versions of the toolchain (macOS version, architecture, Xcode +//! Command Line Tools, Rust, Node, pnpm, git, PHP); +//! 2. the gate steps of `cargo xtask ci` (unless `--skip-gate`), each as +//! its own child process with a timeout; a missing `cargo-deny` is +//! skipped, not failed; +//! 3. the frontend build and `cargo build -p lutra-desktop --features +//! bundled-ui`; +//! 4. one start of the desktop app with `--control PORT` and a fresh data +//! directory, and a scripted self-check over the control channel: +//! open a generated project, open a file, wait for Phpactor, `git.status`, +//! a terminal that runs a command, `ui.screenshot`, and `app.quit`. +//! +//! Every step has a timeout and every child runs in a `lutra_proc` group, so +//! nothing it starts outlives it and the command never hangs. The report +//! (`report.md`, with the step logs, app log and screenshot next to it) is +//! written even when steps fail; the exit status is a failure then. + +use std::fmt::Write as _; +use std::fs::{self, File}; +use std::io::{self, BufRead, BufReader, Read, Write}; +use std::net::{SocketAddr, TcpStream}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; + +use serde_json::{Value, json}; + +use crate::util::{TaskResult, program, repo_root}; + +/// Default control port, the A1 port of cycle C7. +const DEFAULT_PORT: u16 = 7971; + +/// How long one control request may take. +const REQUEST_TIMEOUT: Duration = Duration::from_secs(30); + +/// How long the app may take to answer on its control port. +const START_TIMEOUT: Duration = Duration::from_secs(90); + +/// How long Phpactor may take to download and become ready. +const PHPACTOR_TIMEOUT: Duration = Duration::from_secs(240); + +/// How long the terminal may take to run the probe command. +const TERMINAL_TIMEOUT: Duration = Duration::from_secs(30); + +/// How long the app may take to exit after `app.quit`. +const QUIT_TIMEOUT: Duration = Duration::from_secs(30); + +/// The cursor position query (DSR 6) a shell may send at start. +const CURSOR_QUERY: &str = "\u{1b}[6n"; + +/// The answer to [`CURSOR_QUERY`]: row 1, column 1. +const CURSOR_REPLY: &str = "\u{1b}[1;1R"; + +/// How long a version probe may take. +const VERSION_TIMEOUT: Duration = Duration::from_secs(20); + +/// Lines of a failed step's log copied into the report. +const TAIL_LINES: usize = 40; + +/// The options of one run. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Options { + /// Leave out the gate steps; the build and the self-check still run. + pub skip_gate: bool, + /// Port of the app's control channel. + pub port: u16, + /// Output directory; `None` means `target/mac-report` in the repository. + pub out: Option, +} + +/// Parses the arguments after `mac-report`. +/// +/// # Errors +/// A message for an unknown argument or a bad port. +pub fn parse(args: &[String]) -> TaskResult { + let mut options = Options { + skip_gate: false, + port: DEFAULT_PORT, + out: None, + }; + let mut iter = args.iter(); + while let Some(arg) = iter.next() { + match arg.as_str() { + "--skip-gate" => options.skip_gate = true, + "--port" => { + let value = iter.next().ok_or("--port needs a number")?; + options.port = value + .parse() + .ok() + .filter(|p| *p > 0) + .ok_or_else(|| format!("--port: `{value}` is not a port"))?; + } + "--out" => { + let value = iter.next().ok_or("--out needs a directory")?; + options.out = Some(PathBuf::from(value)); + } + other => return Err(format!("mac-report: unknown argument `{other}`")), + } + } + Ok(options) +} + +/// The outcome of one step. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Status { + /// It worked. + Pass, + /// It failed; the detail says why. + Fail, + /// It did not run; the detail says why. + Skip, +} + +impl Status { + /// The word in the report. + fn label(self) -> &'static str { + match self { + Self::Pass => "PASS", + Self::Fail => "FAIL", + Self::Skip => "SKIP", + } + } +} + +/// One row of the report. +#[derive(Debug, Clone)] +struct Step { + /// Group and name, such as `gate: clippy`. + name: String, + /// The outcome. + status: Status, + /// Wall time in seconds. + seconds: f64, + /// What it found, or the error text. + detail: String, +} + +/// The report being collected. +#[derive(Debug, Default)] +struct Report { + /// `(name, value)` of every version probe. + versions: Vec<(String, String)>, + /// Every step in order. + steps: Vec, +} + +impl Report { + /// Runs `f` as the step `name`, records its outcome and prints a line. + /// `Ok` text is the detail of a pass. + fn step(&mut self, name: &str, f: impl FnOnce() -> Result) -> bool { + println!("==> {name}"); + let start = Instant::now(); + let result = f(); + let seconds = start.elapsed().as_secs_f64(); + let (status, detail) = match result { + Ok(detail) => (Status::Pass, detail), + Err(detail) => (Status::Fail, detail), + }; + println!(" {} ({seconds:.1} s)", status.label()); + if status == Status::Fail { + println!(" {}", first_line(&detail)); + } + self.steps.push(Step { + name: name.to_string(), + status, + seconds, + detail, + }); + status == Status::Pass + } + + /// Records the step `name` as skipped because of `why`. + fn skip(&mut self, name: &str, why: &str) { + println!("==> {name}\n SKIP ({why})"); + self.steps.push(Step { + name: name.to_string(), + status: Status::Skip, + seconds: 0.0, + detail: why.to_string(), + }); + } + + /// The number of failed steps. + fn failures(&self) -> usize { + self.steps + .iter() + .filter(|s| s.status == Status::Fail) + .count() + } + + /// The report as Markdown. + fn markdown(&self, out: &Path, total: Duration) -> String { + let mut text = String::new(); + let _ = writeln!(text, "# Lutra machine report\n"); + let _ = writeln!(text, "- created: {} (Unix time)", unix_now()); + let _ = writeln!( + text, + "- platform: {} {}", + std::env::consts::OS, + std::env::consts::ARCH + ); + let _ = writeln!(text, "- git commit: {}", self.version_of("lutra commit")); + let _ = writeln!( + text, + "- result: {} of {} steps failed, {:.0} s in all", + self.failures(), + self.steps.len(), + total.as_secs_f64() + ); + let _ = writeln!(text, "- files: {}\n", out.display()); + let _ = writeln!(text, "## Steps\n"); + let _ = writeln!(text, "| Step | Result | Time | Detail |"); + let _ = writeln!(text, "|---|---|---:|---|"); + for step in &self.steps { + let _ = writeln!( + text, + "| {} | {} | {:.1} s | {} |", + step.name, + step.status.label(), + step.seconds, + cell(&first_line(&step.detail)) + ); + } + let _ = writeln!(text, "\n## Versions\n"); + for (name, value) in &self.versions { + let _ = writeln!(text, "- **{name}:** {}", cell(value)); + } + let failed: Vec<&Step> = self + .steps + .iter() + .filter(|s| s.status == Status::Fail) + .collect(); + if !failed.is_empty() { + let _ = writeln!(text, "\n## Failures\n"); + for step in failed { + let _ = writeln!(text, "### {}\n\n```text\n{}\n```\n", step.name, step.detail); + } + } + let _ = writeln!(text, "\n## Details\n"); + for step in self.steps.iter().filter(|s| s.status == Status::Pass) { + if step.detail.contains('\n') { + let _ = writeln!(text, "### {}\n\n```text\n{}\n```\n", step.name, step.detail); + } + } + text + } + + /// The value of the version probe `name`, or `?`. + fn version_of(&self, name: &str) -> &str { + self.versions + .iter() + .find(|(n, _)| n == name) + .map_or("?", |(_, v)| v.as_str()) + } +} + +/// Runs the whole check and writes the report. +/// +/// # Errors +/// Fails when the output directory cannot be prepared or the report cannot +/// be written, and, after writing it, when any step failed. +pub fn mac_report(options: &Options) -> TaskResult { + let root = repo_root()?; + let out = options + .out + .clone() + .unwrap_or_else(|| root.join("target").join("mac-report")); + let out = std::path::absolute(&out).unwrap_or(out); + for dir in ["logs", "project", "data"] { + let path = out.join(dir); + if path.exists() { + fs::remove_dir_all(&path).map_err(|e| format!("{}: {e}", path.display()))?; + } + } + fs::create_dir_all(out.join("logs")).map_err(|e| format!("{}: {e}", out.display()))?; + let _ = fs::remove_file(out.join("screenshot.png")); + let start = Instant::now(); + let mut report = Report::default(); + collect_versions(&root, &out, &mut report); + let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".into()); + let runner = Runner { + logs: out.join("logs"), + }; + if options.skip_gate { + report.skip("gate", "--skip-gate"); + } else { + gate(&root, &cargo, &runner, &mut report); + } + let built = build(&root, &cargo, &runner, &mut report); + match built { + Some(desktop) => self_check(&desktop, &out, options.port, &runner, &mut report), + None => report.skip("app", "the desktop app was not built"), + } + let path = out.join("report.md"); + fs::write(&path, report.markdown(&out, start.elapsed())) + .map_err(|e| format!("{}: {e}", path.display()))?; + println!("\nmac-report: report written to {}", path.display()); + match report.failures() { + 0 => Ok(()), + n => Err(format!( + "{n} step(s) failed; send {} back as it is", + path.display() + )), + } +} + +/// Records the versions of the toolchain; a missing tool is noted, never an +/// error. +fn collect_versions(root: &Path, out: &Path, report: &mut Report) { + println!("==> versions"); + let probes: Vec<(&str, &str, Vec<&str>)> = { + let mut probes = Vec::new(); + if cfg!(target_os = "macos") { + probes.push(("macOS", "sw_vers", vec![])); + probes.push(("Xcode CLT", "xcode-select", vec!["-p"])); + probes.push(("clang", "clang", vec!["--version"])); + } + if cfg!(windows) { + probes.push(("Windows", "cmd", vec!["/c", "ver"])); + } + if cfg!(unix) { + probes.push(("architecture", "uname", vec!["-m"])); + } + probes.extend([ + ("lutra commit", "git", vec!["rev-parse", "--short", "HEAD"]), + ("rustc", "rustc", vec!["-V"]), + ("cargo", "cargo", vec!["-V"]), + ("cargo-deny", "cargo", vec!["deny", "--version"]), + ("node", "node", vec!["-v"]), + ("pnpm", "pnpm", vec!["-v"]), + ("git", "git", vec!["--version"]), + ("php", "php", vec!["-v"]), + ("composer", "composer", vec!["--version"]), + ]); + probes + }; + let scratch = out.join("logs").join("version.log"); + for (name, prog, args) in probes { + let value = probe(root, prog, &args, &scratch); + report.versions.push((name.to_string(), value)); + } + let _ = fs::remove_file(&scratch); + for var in ["SHELL", "LANG", "PATH"] { + let value = std::env::var(var).unwrap_or_else(|_| "(not set)".into()); + report.versions.push((format!("${var}"), value)); + } +} + +/// The first lines of a program's output, or why it could not run. +fn probe(root: &Path, prog: &str, args: &[&str], scratch: &Path) -> String { + let runner = Runner { + logs: scratch.parent().map(Path::to_path_buf).unwrap_or_default(), + }; + match runner.run(root, prog, args, scratch, VERSION_TIMEOUT) { + Ok(()) => { + let text = fs::read_to_string(scratch).unwrap_or_default(); + let lines: Vec<&str> = text + .lines() + .map(str::trim) + .filter(|l| !l.is_empty()) + .take(3) + .collect(); + lines.join("; ") + } + Err(e) => format!("not available ({})", first_line(&e)), + } +} + +/// The gate steps of `cargo xtask ci`, each logged and with a timeout. +fn gate(root: &Path, cargo: &str, runner: &Runner, report: &mut Report) { + let minutes = |m: u64| Duration::from_secs(m * 60); + let xtask = std::env::current_exe().ok(); + let cargo_steps: [(&str, Vec<&str>, u64); 3] = [ + ("fmt", vec!["fmt", "--all", "--check"], 10), + ( + "clippy", + vec![ + "clippy", + "--workspace", + "--all-targets", + "--", + "-D", + "warnings", + ], + 60, + ), + ("test", vec!["test", "--workspace"], 60), + ]; + for (name, args, limit) in cargo_steps { + report.step(&format!("gate: {name}"), || { + runner.logged(root, cargo, &args, name, minutes(limit)) + }); + } + for name in ["lints-selftest", "layers", "assets", "cleanroom"] { + let step = format!("gate: {name}"); + match &xtask { + Some(exe) => { + let exe = exe.to_string_lossy(); + report.step(&step, || { + runner.logged(root, &exe, &[name], name, minutes(20)) + }); + } + None => report.skip(&step, "cannot find the xtask binary"), + } + } + if probe( + root, + "cargo", + &["deny", "--version"], + &runner.log("deny-probe"), + ) + .starts_with("not ") + { + report.skip( + "gate: deny", + "cargo-deny is not installed (cargo install cargo-deny --locked)", + ); + } else { + report.step("gate: deny", || { + runner.logged( + root, + cargo, + &["deny", "check", "licenses"], + "deny", + minutes(15), + ) + }); + } + let ui = root.join("ui"); + if !report.step("gate: pnpm install", || { + runner.logged( + &ui, + "pnpm", + &["install", "--frozen-lockfile"], + "pnpm-install", + minutes(20), + ) + }) { + report.skip("gate: ui", "pnpm install failed"); + return; + } + for (name, script, limit) in [ + ("ui lint", "lint", 15), + ("ui typecheck", "typecheck", 15), + ("ui test", "test", 20), + ] { + report.step(&format!("gate: {name}"), || { + runner.logged( + &ui, + "pnpm", + &[script], + &name.replace(' ', "-"), + minutes(limit), + ) + }); + } + match &xtask { + Some(exe) => { + let exe = exe.to_string_lossy(); + report.step("gate: ui licences", || { + runner.logged(root, &exe, &["ui-licences"], "ui-licences", minutes(10)) + }); + } + None => report.skip("gate: ui licences", "cannot find the xtask binary"), + } +} + +/// Builds the frontend and the desktop app with the bundled UI. +/// +/// # Returns +/// The desktop binary, or `None` if a build step failed. +fn build(root: &Path, cargo: &str, runner: &Runner, report: &mut Report) -> Option { + let ui = root.join("ui"); + let minutes = |m: u64| Duration::from_secs(m * 60); + if !ui.join("node_modules").is_dir() + && !report.step("build: pnpm install", || { + runner.logged( + &ui, + "pnpm", + &["install", "--frozen-lockfile"], + "build-pnpm-install", + minutes(20), + ) + }) + { + return None; + } + if !report.step("build: ui", || { + runner.logged(&ui, "pnpm", &["build"], "ui-build", minutes(15)) + }) { + return None; + } + let desktop = target_dir(root).join("debug").join(if cfg!(windows) { + "lutra-desktop.exe" + } else { + "lutra-desktop" + }); + let ok = report.step("build: desktop (bundled-ui)", || { + runner.logged( + root, + cargo, + &["build", "-p", "lutra-desktop", "--features", "bundled-ui"], + "desktop-build", + minutes(60), + )?; + if desktop.is_file() { + Ok(desktop.display().to_string()) + } else { + Err(format!("the build did not produce {}", desktop.display())) + } + }); + ok.then_some(desktop) +} + +/// The Cargo target directory: `CARGO_TARGET_DIR` (relative to the +/// repository root) or `target`. +fn target_dir(root: &Path) -> PathBuf { + match std::env::var_os("CARGO_TARGET_DIR").filter(|v| !v.is_empty()) { + Some(dir) => root.join(dir), + None => root.join("target"), + } +} + +/// Starts the app once and drives the self-check over its control channel. +fn self_check(desktop: &Path, out: &Path, port: u16, runner: &Runner, report: &mut Report) { + let project = out.join("project"); + if !report.step("app: demo project", || { + make_project(&project, runner).map(|()| project.display().to_string()) + }) { + report.skip("app", "no demo project"); + return; + } + let app_log = out.join("logs").join("app.log"); + let mut app = None; + let mut client = None; + report.step("app: start", || { + let (child, connected) = start_app(desktop, out, port, &app_log)?; + app = Some(child); + client = Some(connected); + Ok(format!("control channel on 127.0.0.1:{port}")) + }); + let (Some(mut app), Some(mut client)) = (app, client) else { + report.skip("app: checks", "the app did not start"); + return; + }; + report.step("app: subscribe to events", || { + client + .call("events.subscribe", json!({})) + .map(|v| v.to_string()) + }); + let project_ok = report.step("app: project.open", || { + client + .execute("project.open", json!({ "path": project })) + .map(|v| compact(&v)) + }); + let mut buffer = None; + if project_ok { + report.step("app: file.open", || { + let opened = client.execute("file.open", json!({ "path": "src/Greeter.php" }))?; + buffer = opened.get("id").and_then(Value::as_u64); + let text = opened.get("text").and_then(Value::as_str).unwrap_or(""); + if text.contains("class Greeter") { + Ok(format!("buffer {}", buffer.unwrap_or(0))) + } else { + Err(format!("unexpected file text: {}", compact(&opened))) + } + }); + report.step("app: Phpactor ready", || wait_for_phpactor(&mut client)); + match buffer { + Some(id) => { + report.step("app: lsp.hover", || hover(&mut client, id)); + } + None => report.skip("app: lsp.hover", "file.open failed"), + } + report.step("app: git.status", || git_status(&mut client)); + } else { + report.skip("app: project checks", "project.open failed"); + } + report.step("app: terminal", || terminal(&mut client)); + let shot = out.join("screenshot.png"); + report.step("app: ui.screenshot", || { + std::thread::sleep(Duration::from_secs(2)); + client.call("ui.screenshot", json!({ "path": shot }))?; + png_summary(&shot) + }); + report.step("app: quit", || { + let _ = client.execute("app.quit", json!({})); + let deadline = Instant::now() + QUIT_TIMEOUT; + loop { + match app.try_wait() { + Ok(Some(status)) => return Ok(format!("exited with {status}")), + Ok(None) if Instant::now() >= deadline => { + return Err(format!( + "still running {} s after app.quit; killed", + QUIT_TIMEOUT.as_secs() + )); + } + Ok(None) => std::thread::sleep(Duration::from_millis(200)), + Err(e) => return Err(e.to_string()), + } + } + }); + drop(app); + let log = tail(&app_log, TAIL_LINES); + report + .versions + .push(("app log (tail)".into(), log.replace('\n', " ⏎ "))); +} + +/// Writes a small PHP project with one commit and one uncommitted change. +/// +/// # Errors +/// A message if a file cannot be written or git fails. +fn make_project(dir: &Path, runner: &Runner) -> Result<(), String> { + let write = |rel: &str, text: &str| { + let path = dir.join(rel); + if let Some(parent) = path.parent() { + fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?; + } + fs::write(&path, text).map_err(|e| format!("{}: {e}", path.display())) + }; + write( + "composer.json", + "{\n \"name\": \"lutra/report-demo\",\n \"autoload\": { \"psr-4\": { \"Demo\\\\\": \"src/\" } }\n}\n", + )?; + write( + "src/Greeter.php", + "greet('Lutra');\n", + )?; + write("README.md", "# Report demo\n")?; + let git = + |args: &[&str], name: &str| runner.logged(dir, "git", args, name, Duration::from_secs(60)); + git(&["init", "-q", "-b", "main"], "git-init")?; + git(&["add", "-A"], "git-add")?; + git( + &[ + "-c", + "user.name=Lutra Report", + "-c", + "user.email=report@lutra.invalid", + "-c", + "commit.gpgsign=false", + "commit", + "-q", + "-m", + "Initial commit", + ], + "git-commit", + )?; + write("README.md", "# Report demo\n\nChanged after the commit.\n") +} + +/// Starts the desktop app and connects to its control channel. +/// +/// # Errors +/// A message with the app log's tail if it exits early or does not answer +/// within [`START_TIMEOUT`]. +fn start_app( + desktop: &Path, + out: &Path, + port: u16, + log: &Path, +) -> Result<(lutra_proc::Child, Client), String> { + let file = File::create(log).map_err(|e| format!("{}: {e}", log.display()))?; + let err = file.try_clone().map_err(|e| e.to_string())?; + let mut command = Command::new(desktop); + command + .arg("--control") + .arg(port.to_string()) + .arg("--data-dir") + .arg(out.join("data")) + .stdin(Stdio::null()) + .stdout(Stdio::from(file)) + .stderr(Stdio::from(err)); + let mut child = lutra_proc::spawn(command) + .map_err(|e| format!("cannot start {}: {e}", desktop.display()))?; + let deadline = Instant::now() + START_TIMEOUT; + loop { + if let Ok(Some(status)) = child.try_wait() { + return Err(format!( + "the app exited before it answered ({status}):\n{}", + tail(log, TAIL_LINES) + )); + } + if let Ok(mut client) = Client::connect(port) + && client.call("app.ping", json!({})).is_ok() + { + return Ok((child, client)); + } + if Instant::now() >= deadline { + return Err(format!( + "no answer on port {port} within {} s:\n{}", + START_TIMEOUT.as_secs(), + tail(log, TAIL_LINES) + )); + } + std::thread::sleep(Duration::from_millis(500)); + } +} + +/// Waits until the language server is ready, downloading Phpactor first if +/// it is missing. +/// +/// # Errors +/// A message with the last status if it fails or takes longer than +/// [`PHPACTOR_TIMEOUT`]. +fn wait_for_phpactor(client: &mut Client) -> Result { + let deadline = Instant::now() + PHPACTOR_TIMEOUT; + let mut asked_download = false; + loop { + let toolchain = client.execute("toolchain.status", json!({}))?; + let phpactor = toolchain + .pointer("/phpactor/state") + .and_then(Value::as_str) + .unwrap_or(""); + let php_found = toolchain + .pointer("/php/found") + .and_then(Value::as_bool) + .unwrap_or(false); + if phpactor == "missing" && php_found && !asked_download { + client.execute("toolchain.downloadPhpactor", json!({}))?; + asked_download = true; + } + let lsp = client.execute("lsp.status", json!({}))?; + match lsp.get("state").and_then(Value::as_str) { + Some("ready") => { + return Ok(format!( + "startupMs {}\ntoolchain: {}\nlsp: {}", + lsp.get("startupMs").map_or("?".into(), Value::to_string), + compact(&toolchain), + compact(&lsp) + )); + } + Some("failed") => { + return Err(format!( + "the language server failed\nlsp: {}\ntoolchain: {}", + compact(&lsp), + compact(&toolchain) + )); + } + _ => {} + } + if Instant::now() >= deadline { + return Err(format!( + "not ready within {} s +lsp: {} +toolchain: {}", + PHPACTOR_TIMEOUT.as_secs(), + compact(&lsp), + compact(&toolchain) + )); + } + std::thread::sleep(Duration::from_millis(500)); + } +} + +/// Hovers over `Greeter` in `new Greeter()` and expects its doc comment. +/// +/// # Errors +/// A message if the request fails or the hover is empty. +fn hover(client: &mut Client, buffer: u64) -> Result { + let deadline = Instant::now() + Duration::from_secs(30); + loop { + let result = client.execute( + "lsp.hover", + json!({ "id": buffer, "position": { "line": 13, "column": 17 } }), + )?; + let contents = result.get("contents").and_then(Value::as_str).unwrap_or(""); + if contents.contains("Greeter") { + return Ok(first_line(contents)); + } + if Instant::now() >= deadline { + return Err(format!("no hover for Greeter: {}", compact(&result))); + } + std::thread::sleep(Duration::from_secs(1)); + } +} + +/// Checks `git.status` of the demo project: a usable git, branch `main` +/// and the uncommitted `README.md`. +/// +/// # Errors +/// A message with the result if anything is missing. +fn git_status(client: &mut Client) -> Result { + let status = client.execute("git.status", json!({}))?; + let available = status.get("available").and_then(Value::as_bool) == Some(true); + let branch = status + .pointer("/repo/branch") + .and_then(Value::as_str) + .unwrap_or(""); + let readme = status + .get("files") + .and_then(Value::as_array) + .is_some_and(|files| { + files + .iter() + .any(|f| f.get("path").and_then(Value::as_str) == Some("README.md")) + }); + if available && branch == "main" && readme { + Ok(format!("branch {branch}, README.md modified")) + } else { + Err(format!("unexpected git.status: {}", compact(&status))) + } +} + +/// Opens a terminal with the default shell, runs a command that prints +/// `LUTRA42` only when the shell evaluates it, and closes it. Cursor +/// position queries ([`CURSOR_QUERY`]) are answered as the frontend's +/// terminal would, because some shells (PowerShell behind ConPTY) wait for +/// the answer before they read input. +/// +/// # Errors +/// A message with the terminal's output if the marker does not appear +/// within [`TERMINAL_TIMEOUT`]. +fn terminal(client: &mut Client) -> Result { + let created = client.execute("terminal.create", json!({ "cols": 100, "rows": 30 }))?; + let id = created + .get("terminalId") + .cloned() + .ok_or_else(|| format!("no terminalId: {}", compact(&created)))?; + let line = if cfg!(windows) { + "echo \"LUTRA$(6*7)\"\r" + } else { + "echo LUTRA$((6*7))\r" + }; + client.execute("terminal.input", json!({ "terminalId": id, "data": line }))?; + let deadline = Instant::now() + TERMINAL_TIMEOUT; + let mut output = String::new(); + let mut answered = 0; + let found = loop { + for event in client.take_events() { + if event.get("kind").and_then(Value::as_str) == Some("terminalOutput") + && event.get("terminalId") == Some(&id) + { + output.push_str(event.get("data").and_then(Value::as_str).unwrap_or("")); + } + } + let asked = output.matches(CURSOR_QUERY).count(); + if asked > answered { + let _ = client.execute( + "terminal.input", + json!({ "terminalId": id, "data": CURSOR_REPLY }), + ); + answered = asked; + } + if output.contains("LUTRA42") { + break true; + } + if Instant::now() >= deadline { + break false; + } + client.pump(Duration::from_millis(500)); + }; + let _ = client.execute("terminal.close", json!({ "terminalId": id })); + let skip = output.chars().count().saturating_sub(1500); + let shown: String = output.chars().skip(skip).collect(); + if found { + Ok(format!( + "the shell ran the probe command\noutput tail:\n{shown}" + )) + } else { + Err(format!( + "no LUTRA42 within {} s; output:\n{shown}", + TERMINAL_TIMEOUT.as_secs() + )) + } +} + +/// Reads the size of a PNG from its header. +/// +/// # Errors +/// A message if the file is missing or not a PNG. +fn png_summary(path: &Path) -> Result { + let bytes = fs::read(path).map_err(|e| format!("{}: {e}", path.display()))?; + let word = |at: usize| -> Option { + let b = bytes.get(at..at + 4)?; + Some(u32::from_be_bytes([ + *b.first()?, + *b.get(1)?, + *b.get(2)?, + *b.get(3)?, + ])) + }; + if !bytes.starts_with(b"\x89PNG") { + return Err("the screenshot is not a PNG".into()); + } + let (Some(w), Some(h)) = (word(16), word(20)) else { + return Err("the PNG header is cut off".into()); + }; + Ok(format!( + "{w}x{h} px, {} KB (the window opens at 1200x800 points: about 2400x1600 on a Retina display)", + bytes.len() / 1024 + )) +} + +/// Runs child processes with their output in log files and a timeout. +struct Runner { + /// The log folder. + logs: PathBuf, +} + +impl Runner { + /// The log file of the step `name`. + fn log(&self, name: &str) -> PathBuf { + self.logs.join(format!("{name}.log")) + } + + /// Runs a program with its output in the log of `name`. + /// + /// # Returns + /// The log's path as the detail of a pass. + /// + /// # Errors + /// See [`Runner::run`]. + fn logged( + &self, + dir: &Path, + prog: &str, + args: &[&str], + name: &str, + timeout: Duration, + ) -> Result { + let log = self.log(name); + self.run(dir, prog, args, &log, timeout)?; + Ok(format!("log: {}", log.display())) + } + + /// Runs a program in its own `lutra_proc` group with standard output + /// and error in `log`, killing the group after `timeout`. + /// + /// # Errors + /// A message with the end of the log if the program cannot start, + /// exits unsuccessfully or times out. + fn run( + &self, + dir: &Path, + prog: &str, + args: &[&str], + log: &Path, + timeout: Duration, + ) -> Result<(), String> { + let file = File::create(log).map_err(|e| format!("{}: {e}", log.display()))?; + let err = file.try_clone().map_err(|e| e.to_string())?; + let mut command = Command::new(program(prog)); + command + .args(args) + .current_dir(dir) + .stdin(Stdio::null()) + .stdout(Stdio::from(file)) + .stderr(Stdio::from(err)); + let shown = format!("{prog} {}", args.join(" ")); + let mut child = + lutra_proc::spawn(command).map_err(|e| format!("cannot start `{shown}`: {e}"))?; + let deadline = Instant::now() + timeout; + let status = loop { + match child.try_wait() { + Ok(Some(status)) => break status, + Ok(None) if Instant::now() >= deadline => { + let _ = child.kill_and_wait(); + return Err(format!( + "`{shown}` timed out after {} s and was killed\n{}", + timeout.as_secs(), + tail(log, TAIL_LINES) + )); + } + Ok(None) => std::thread::sleep(Duration::from_millis(200)), + Err(e) => return Err(format!("`{shown}`: {e}")), + } + }; + if status.success() { + Ok(()) + } else { + Err(format!( + "`{shown}` failed ({status})\n{}", + tail(log, TAIL_LINES) + )) + } + } +} + +/// A JSON-lines client of the control channel that keeps the event lines +/// it reads between responses. +struct Client { + /// The connection, read through a buffer. + reader: BufReader, + /// The connection, written directly. + writer: TcpStream, + /// The next request id. + next_id: u64, + /// A line read only partly before a read timed out. + partial: Vec, + /// Event lines not taken yet. + events: Vec, +} + +impl Client { + /// Connects to `127.0.0.1:port`. + /// + /// # Errors + /// The connection error. + fn connect(port: u16) -> io::Result { + let addr = SocketAddr::from(([127, 0, 0, 1], port)); + let stream = TcpStream::connect_timeout(&addr, Duration::from_secs(2))?; + stream.set_read_timeout(Some(Duration::from_millis(500)))?; + stream.set_write_timeout(Some(REQUEST_TIMEOUT))?; + Ok(Self { + reader: BufReader::new(stream.try_clone()?), + writer: stream, + next_id: 1, + partial: Vec::new(), + events: Vec::new(), + }) + } + + /// Runs the engine command `command`. + /// + /// # Errors + /// See [`Client::call`]. + fn execute(&mut self, command: &str, params: Value) -> Result { + self.call( + "engine.execute", + json!({ "command": command, "params": params }), + ) + .map_err(|e| format!("{command}: {e}")) + } + + /// Sends one request and waits for its response, keeping the events + /// that arrive meanwhile. + /// + /// # Errors + /// The error object of the response, a broken connection, or no + /// response within [`REQUEST_TIMEOUT`]. + fn call(&mut self, method: &str, params: Value) -> Result { + let id = self.next_id; + self.next_id += 1; + let mut line = json!({ "id": id, "method": method, "params": params }).to_string(); + line.push('\n'); + self.writer + .write_all(line.as_bytes()) + .map_err(|e| format!("cannot send {method}: {e}"))?; + let deadline = Instant::now() + REQUEST_TIMEOUT; + loop { + match self.read_line() { + Ok(Some(value)) => { + if let Some(event) = value.get("event") { + self.events.push(event.clone()); + } else if value.get("id").and_then(Value::as_u64) == Some(id) { + if let Some(error) = value.get("error") { + return Err(compact(error)); + } + return Ok(value.get("result").cloned().unwrap_or(Value::Null)); + } + } + Ok(None) => {} + Err(e) => return Err(format!("{method}: connection lost: {e}")), + } + if Instant::now() >= deadline { + return Err(format!( + "{method}: no response within {} s", + REQUEST_TIMEOUT.as_secs() + )); + } + } + } + + /// Reads event lines for up to `wait`. + fn pump(&mut self, wait: Duration) { + let deadline = Instant::now() + wait; + while Instant::now() < deadline { + match self.read_line() { + Ok(Some(value)) => { + if let Some(event) = value.get("event") { + self.events.push(event.clone()); + } + } + Ok(None) => {} + Err(_) => return, + } + } + } + + /// The events read so far, oldest first. + fn take_events(&mut self) -> Vec { + std::mem::take(&mut self.events) + } + + /// Reads one line; `Ok(None)` when the read timed out first or the line + /// is not JSON. Bytes of a line cut off by the timeout are kept for the + /// next call. + /// + /// # Errors + /// End of stream or another read error. + fn read_line(&mut self) -> io::Result> { + match self.reader.read_until(b'\n', &mut self.partial) { + Ok(0) => Err(io::Error::new(io::ErrorKind::UnexpectedEof, "closed")), + Ok(_) if self.partial.ends_with(b"\n") => { + let line = std::mem::take(&mut self.partial); + Ok(serde_json::from_slice(&line).ok()) + } + Ok(_) => Ok(None), + Err(e) + if matches!( + e.kind(), + io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut + ) => + { + Ok(None) + } + Err(e) => Err(e), + } + } +} + +/// The last `lines` lines of a text file, or a note that it is unreadable. +fn tail(path: &Path, lines: usize) -> String { + let mut bytes = Vec::new(); + if File::open(path) + .and_then(|mut f| f.read_to_end(&mut bytes)) + .is_err() + { + return format!("({} cannot be read)", path.display()); + } + let text = String::from_utf8_lossy(&bytes); + let all: Vec<&str> = text.lines().collect(); + let start = all.len().saturating_sub(lines); + all.get(start..).unwrap_or_default().join("\n") +} + +/// The first line of `text`, at most 300 characters. +fn first_line(text: &str) -> String { + text.lines() + .next() + .unwrap_or("") + .chars() + .take(300) + .collect() +} + +/// `text` safe for one Markdown table cell. +fn cell(text: &str) -> String { + text.replace('|', "\\|").replace('\n', " ") +} + +/// A JSON value on one line, at most 2000 characters. +fn compact(value: &Value) -> String { + value.to_string().chars().take(2000).collect() +} + +/// Seconds since the Unix epoch. +fn unix_now() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |d| d.as_secs()) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn strings(args: &[&str]) -> Vec { + args.iter().map(|s| s.to_string()).collect() + } + + #[test] + fn parses_options() { + let default = parse(&[]).unwrap(); + assert_eq!(default.port, DEFAULT_PORT); + assert!(!default.skip_gate); + let given = parse(&strings(&["--skip-gate", "--port", "7001", "--out", "x"])).unwrap(); + assert_eq!( + given, + Options { + skip_gate: true, + port: 7001, + out: Some(PathBuf::from("x")), + } + ); + assert!(parse(&strings(&["--port", "0"])).is_err()); + assert!(parse(&strings(&["--port"])).is_err()); + assert!(parse(&strings(&["--bogus"])).is_err()); + } + + #[test] + fn report_lists_failures_with_their_text() { + let mut report = Report::default(); + report.step("ok", || Ok("fine".into())); + report.step("broken", || Err("first | line\nsecond".into())); + report.skip("later", "not needed"); + let text = report.markdown(Path::new("out"), Duration::from_secs(3)); + assert_eq!(report.failures(), 1); + assert!(text.contains("| broken | FAIL |")); + assert!(text.contains("first \\| line")); + assert!(text.contains("### broken\n\n```text\nfirst | line\nsecond\n```")); + assert!(text.contains("| later | SKIP |")); + } + + #[test] + fn png_summary_reads_the_size() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("a.png"); + let mut bytes = b"\x89PNG\r\n\x1a\n\0\0\0\rIHDR".to_vec(); + bytes.extend_from_slice(&2400u32.to_be_bytes()); + bytes.extend_from_slice(&1600u32.to_be_bytes()); + fs::write(&path, &bytes).unwrap(); + assert!(png_summary(&path).unwrap().starts_with("2400x1600 px")); + fs::write(&path, b"GIF").unwrap(); + assert!(png_summary(&path).is_err()); + } + + #[test] + fn runner_times_out_and_reports_failures() { + let dir = tempfile::tempdir().unwrap(); + let runner = Runner { + logs: dir.path().to_path_buf(), + }; + let log = dir.path().join("x.log"); + let (sleep, sleep_args): (&str, Vec<&str>) = if cfg!(windows) { + ("cmd", vec!["/c", "ping -n 30 127.0.0.1 >nul"]) + } else { + ("sh", vec!["-c", "sleep 30"]) + }; + let start = Instant::now(); + let err = runner + .run(dir.path(), sleep, &sleep_args, &log, Duration::from_secs(1)) + .unwrap_err(); + assert!(err.contains("timed out"), "{err}"); + assert!(start.elapsed() < Duration::from_secs(20)); + let (fail, fail_args): (&str, Vec<&str>) = if cfg!(windows) { + ("cmd", vec!["/c", "echo boom & exit 3"]) + } else { + ("sh", vec!["-c", "echo boom; exit 3"]) + }; + let err = runner + .run(dir.path(), fail, &fail_args, &log, Duration::from_secs(20)) + .unwrap_err(); + assert!(err.contains("boom"), "{err}"); + } + + #[test] + fn tail_keeps_the_last_lines() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("t.log"); + fs::write(&path, "a\nb\nc\n").unwrap(); + assert_eq!(tail(&path, 2), "b\nc"); + assert!(tail(&dir.path().join("none"), 2).contains("cannot be read")); + } +} diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 0da99b9..86c4599 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -8,13 +8,15 @@ mod cleanroom; mod layers; mod licences; mod lints; +mod macreport; mod tasks; mod util; use std::process::ExitCode; /// Usage text printed for `help` and unknown subcommands. -const USAGE: &str = "usage: cargo xtask +const USAGE: &str = concat!( + "usage: cargo xtask commands: ci [--skip-ui] the full quality gate (run before every commit) @@ -24,7 +26,12 @@ commands: ui-licences check the licences of the frontend's production dependencies lints-selftest prove that shipped unwrap() fails clippy and test unwrap() passes dev [-- ARGS] run the desktop app in development mode, ARGS go to the app - fixtures create Symfony and Laravel reference projects in target/fixtures/"; + fixtures create Symfony and Laravel reference projects in target/fixtures/ + ", + "mac-report [--skip-gate] [--port PORT] [--out DIR] + check this machine end to end and write one report file + (default target/mac-report/report.md, port 7971)" +); /// Dispatches to the subcommand named by the first argument. fn main() -> ExitCode { @@ -50,6 +57,7 @@ fn main() -> ExitCode { tasks::dev(&app_args) } "fixtures" => tasks::fixtures(), + "mac-report" => macreport::parse(rest).and_then(|o| macreport::mac_report(&o)), "help" | "--help" | "-h" => { println!("{USAGE}"); Ok(())