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

@ -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 `<temp>/lutra-control/<port>/`, 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) |

View file

@ -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) |

221
docs/macos.md Normal file
View file

@ -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/<you>/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) |