B1: alpha installers (NSIS, DMG), identifier com.tyrveil.lutra with data migration
- App identifier com.tyrveil.lutra (D26) in tauri.conf.json and rendezvous::APP_IDENTIFIER; a test keeps them equal. - First normal start copies settings.json, recovery/ and tools/ once from the dev.lutra.desktop directories (staging dir + rename, logged, info notification); old directories stay untouched. - Bundling on: per-user NSIS setup (English, German, Start menu, optional desktop shortcut, uninstaller) and DMG; `cargo xtask bundle` builds the platform's installer, joining the DMG backgrounds into a HiDPI TIFF on macOS. build.rs also writes icons/512x512.png for the .icns. - Installer images from the banner, designed by Amy, generated by `cargo xtask installer-images` (assets/installer/, ASSETS.md rows); approved by Daniel. - docs/install.md (SmartScreen, Gatekeeper, uninstall, data locations), README install section, architecture, development and macOS notes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
071b2a5644
commit
bd225d9e3a
22 changed files with 1367 additions and 17 deletions
|
|
@ -69,7 +69,7 @@ As built in M0:
|
|||
### CLI and single instance (M3.7)
|
||||
|
||||
- **Rendezvous file:** a desktop that owns the single instance serves a second, token-protected control listener on a free port of `127.0.0.1` (`lutra_control::start_with_token`) and writes `<data_dir>/instance.json` = `{port, token, pid, version}` (`lutra_control::rendezvous`). The token is 32 bytes from the OS generator (`getrandom`), hex. The file is written to a temporary file and renamed, so readers never see half a file; on exit the app removes it if it still holds its own token.
|
||||
- **Directory:** `LUTRA_RENDEZVOUS_DIR` if set, else `rendezvous::default_data_dir()`, which computes Tauri's `app_data_dir()` for the identifier `dev.lutra.desktop` without Tauri (`%APPDATA%\dev.lutra.desktop` on Windows, `~/Library/Application Support/dev.lutra.desktop` on macOS, `$XDG_DATA_HOME` or `~/.local/share` + the identifier elsewhere), so the CLI and the desktop agree without sharing a runtime.
|
||||
- **Directory:** `LUTRA_RENDEZVOUS_DIR` if set, else `rendezvous::default_data_dir()`, which computes Tauri's `app_data_dir()` for the identifier `com.tyrveil.lutra` (`rendezvous::APP_IDENTIFIER`) without Tauri (`%APPDATA%\com.tyrveil.lutra` on Windows, `~/Library/Application Support/com.tyrveil.lutra` on macOS, `$XDG_DATA_HOME` or `~/.local/share` + the identifier elsewhere), so the CLI and the desktop agree without sharing a runtime.
|
||||
- **Security:** only the user may read the token. Unix: the file is created with mode `0600`. Windows: it lives in the user's roaming AppData folder, whose inherited ACL grants the user, `SYSTEM` and Administrators only (checked with `icacls` in the M3.7 live check); Lutra sets no ACL of its own. Both listeners bind `127.0.0.1` only. On the token listener the first request must be `app.auth {token}` within 10 s (`AUTH_TIMEOUT`); a wrong token, another method or garbage gets `unauthorized` and the connection is closed. Tokens are compared in constant time. The `--control PORT` listener stays open (no token) for development and agents; it is opt-in and documented as such.
|
||||
- **Second start:** `lutra-desktop [PATH]` without `--control` reads the rendezvous file first. If the listener answers, accepts the token and pings, the start forwards `PATH` (folder → `project.open`, file → `file.open`), calls `app.focus` and exits 0. If the file is missing, unreadable, invalid, or its port refuses or rejects the token, it is stale: this start becomes the instance and replaces the file. Two starts in the same instant can both become instances; the later file wins (accepted, rare).
|
||||
- **Development instances:** a start with `--control PORT` skips the single instance (no forwarding, no rendezvous file) so parallel agents' instances never forward to each other, unless `LUTRA_RENDEZVOUS_DIR` is set, which opts it into the single instance in that directory (used for isolated live checks).
|
||||
|
|
@ -750,13 +750,15 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
| Text buffer | `ropey` (MIT) in `crates/text`. | Mature rope with line and UTF-16 helpers. |
|
||||
| Clippy panic lints | `unwrap_used`, `expect_used`, `panic`, `unreachable`, `todo`, `unimplemented`, `indexing_slicing`, `string_slice` are denied workspace-wide; `clippy.toml` allows them in `#[test]`/`#[cfg(test)]`; integration tests in `tests/` and `testkit` allow them at crate level. `missing_docs` is denied too, to back the doc-comment code style. `unsafe_code` is denied; a crate that needs it allows it locally with a doc comment saying why. | AGENTS.md › Never crash. |
|
||||
| Desktop dev mode | Plain `cargo build`/`cargo run -p lutra-desktop` is a Tauri dev build that loads the Vite dev server. `cargo xtask dev [-- ARGS]` starts both. A self-contained build embeds `ui/dist` through the `bundled-ui` feature. | Keeps `cargo build --workspace` independent of the frontend build. |
|
||||
| App identifier | `dev.lutra.desktop` is a placeholder. The final reverse-DNS identifier depends on the project's domain and hosting, which are the owner's decision (execution plan §4); bundling stays off until then. | Tauri requires an identifier to build. |
|
||||
| App identifier | `com.tyrveil.lutra` (owner, D26, 2026-10-31), in `tauri.conf.json` and `rendezvous::APP_IDENTIFIER` (a test keeps them equal). It replaced the placeholder `dev.lutra.desktop`: the first normal start under the new identifier, when its data directory does not exist and an old directory does, copies `settings.json`, `recovery/` and `tools/` from the old directories into a staging folder next to the new data directory, renames it into place, logs the copy to stderr and shows an info notification (`apps/lutra-desktop/src/migrate.rs`). The old directories stay; the rendezvous file and the webview data are not copied. Isolated starts never migrate. | Tauri derives the data directories from the identifier; without the copy, alpha testers would lose their settings, journal and Phpactor download. Staging plus rename makes a half-done copy retry on the next start instead of counting as done. |
|
||||
| Installers | `bundle.active` with `targets` NSIS and DMG; `cargo xtask bundle` runs `cargo tauri build --bundles nsis\|dmg --features bundled-ui` for the current platform and prints the installer and its size. NSIS: `installMode: currentUser` (no admin, `%LOCALAPPDATA%\Lutra`), English and German following the OS, Start menu shortcut, desktop shortcut as a finish-page option, uninstaller with the opt-in "delete app data" box; header and sidebar BMPs from `assets/installer/`. DMG: 720 × 400 window with the app at (100, 184) and Applications at (326, 184) over `dmg-background.png`; on macOS `xtask bundle` joins the 1x and 2x PNGs into a HiDPI TIFF with `tiffutil` and passes it through `--config`. `build.rs` also writes `icons/512x512.png`, from which the macOS bundler makes the `.icns`. Unsigned (owner, D26). Install, unsigned-start and data-location steps: [`install.md`](install.md). Live check (Windows 11, 2026-10-31, measured): `cargo xtask bundle` 3 min 42 s release build with 4 jobs, setup 4.95 MiB; `/S /D=<test dir>` installed in about 1 s, 18.8 MiB on disk (`lutra-desktop.exe` 18.6 MiB, `uninstall.exe` 0.2 MiB), Start menu and desktop shortcuts and the HKCU uninstall entry present; the installed app started with `--control --data-dir` and showed a project in its screenshot; `uninstall.exe /S` removed the files, both shortcuts and the entry. | Tauri's bundler covers both formats without extra tools on Windows (it fetches NSIS) or macOS (`hdiutil`). A per-user install needs no UAC prompt, which suits an alpha. The installer images are generated by `cargo xtask installer-images` from the banner, so they can be regenerated. |
|
||||
| App icon | `apps/lutra-desktop/build.rs` downscales the owner's master `assets/app-icon/icon.png` (720 px, see ASSETS.md) with an area-averaging box filter into the gitignored `apps/lutra-desktop/icons/`: `icon.png` (256 px window icon) and a multi-size `icon.ico` (16, 32, 48, 64, 128, 256 px, PNG entries). If the master is missing or unreadable, the build prints a cargo warning and uses the placeholder generated in code (rounded otter-brown square with a pale stone). | The icon is the owner's (M1.14); decoding uses the `png` build dependency already present, so no new dependency. The fallback keeps a checkout without the asset buildable and never fails the build over an icon. |
|
||||
|
||||
## Revision history
|
||||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-31 | minor | C7 B1: app identifier `com.tyrveil.lutra` with the one-time copy from `dev.lutra.desktop`, NSIS and DMG installers, `cargo xtask bundle` |
|
||||
| 2026-10-31 | minor | C7 A3: `git.mergeMessage` and the merge message prefill, `git.ignore` and the Changes context menu, gutter markers kept on their line, per-module `COMMAND_IDS` for the command listing test |
|
||||
| 2026-10-30 | minor | M4.7: blame (`git.blame` with `--contents` from the buffer, the annotation gutter by age, hover with the commit message, `vcs.toggleBlame`, `vcs.showCommit`) |
|
||||
| 2026-10-28 | minor | M4.6: history backend (`git.log`, `git.showCommit`, `git.showAt`), the shared hook for new git commands, the Log tab, diffs at a commit |
|
||||
|
|
|
|||
|
|
@ -19,6 +19,8 @@ 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
|
||||
cargo xtask demo-project ../lutra-demo # offline demo project for docs/alpha-checklist.md
|
||||
cargo xtask bundle # this platform's installer (NSIS setup on Windows, DMG on macOS), see install.md
|
||||
cargo xtask installer-images # regenerate assets/installer/ from docs/images/banner.png
|
||||
```
|
||||
|
||||
`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).
|
||||
|
|
@ -61,6 +63,7 @@ No inline comments. Doc comment blocks above modules, functions, types and field
|
|||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-31 | minor | B1: `cargo xtask bundle`, `cargo xtask installer-images` |
|
||||
| 2026-10-31 | minor | A2: `cargo xtask demo-project` |
|
||||
| 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` |
|
||||
|
|
|
|||
72
docs/install.md
Normal file
72
docs/install.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# Installing Lutra
|
||||
|
||||
> **Status:** draft, alpha installers · **Last updated:** 2026-10-31
|
||||
|
||||
Lutra's alpha comes as an installer for Windows (a setup `.exe`) and macOS (a `.dmg`). Both are **not signed yet**, so Windows and macOS warn before the first start; the steps below get past that once. Linux has no installer yet: build it from source ([`development.md`](development.md)).
|
||||
|
||||
The installers contain the desktop app only. The `lutra` command-line tool (`lutra .`, `lutra mcp`) is not in them yet; build it with `cargo build --release -p lutra-cli` if you need it.
|
||||
|
||||
## Building an installer
|
||||
|
||||
On the platform you want the installer for:
|
||||
|
||||
```sh
|
||||
cargo xtask bundle
|
||||
```
|
||||
|
||||
It builds the release app with the bundled UI and prints the installer's path and size: `target/release/bundle/nsis/Lutra_<version>_x64-setup.exe` on Windows, `target/release/bundle/dmg/Lutra_<version>_aarch64.dmg` on macOS. It needs the Tauri CLI (`cargo install tauri-cli --locked`) and, on macOS, the Xcode Command Line Tools ([`macos.md`](macos.md)).
|
||||
|
||||
## Windows
|
||||
|
||||
Lutra installs for your user only: no administrator rights, no UAC prompt. It needs Microsoft Edge WebView2, which Windows 10 and 11 already have; if it is missing, the setup downloads it.
|
||||
|
||||
1. Start `Lutra_<version>_x64-setup.exe`.
|
||||
2. Windows SmartScreen says "Windows protected your PC", because the setup is not signed. Click **More info**, check that the app is `Lutra_<version>_x64-setup.exe` and the publisher is "Unknown publisher", then click **Run anyway**. If you downloaded the file with a browser, the browser may ask first whether to keep it.
|
||||
3. The setup runs in English or German, following Windows. Click **Next**, keep or change the folder (default `%LOCALAPPDATA%\Lutra`), click **Install**.
|
||||
4. On the last page, tick **Create desktop shortcut** if you want one, and click **Finish**.
|
||||
|
||||
Lutra is now in the Start menu as **Lutra**. Installing a newer setup over it updates it in place and keeps your settings.
|
||||
|
||||
For scripts: `Lutra_<version>_x64-setup.exe /S` installs silently with both shortcuts, `/D=C:\path` (last argument) picks the folder, `/NS` skips the shortcuts.
|
||||
|
||||
### Uninstalling on Windows
|
||||
|
||||
Settings → Apps → Installed apps → **Lutra** → … → **Uninstall**, or run `uninstall.exe` in the install folder. The uninstaller removes the app and its shortcuts. Your settings, recovery journal and Phpactor stay unless you tick **Delete the application data**.
|
||||
|
||||
## macOS
|
||||
|
||||
The DMG holds the app for Apple Silicon (M1 or newer), macOS 11 or newer.
|
||||
|
||||
1. Open `Lutra_<version>_aarch64.dmg` and drag **Lutra** onto **Applications**. Eject the DMG.
|
||||
2. The first start is blocked because the app is not signed or notarised. In **Applications**, **right-click** (or Control-click) Lutra → **Open**, and click **Open** in the dialog. On macOS 15 Sequoia and newer that dialog has no Open button: click **Done**, then open **System Settings → Privacy & Security**, scroll to "Lutra was blocked", click **Open Anyway** and confirm with your password.
|
||||
3. Alternatively, remove the quarantine flag once in Terminal and start Lutra normally:
|
||||
|
||||
```sh
|
||||
xattr -dr com.apple.quarantine /Applications/Lutra.app
|
||||
```
|
||||
|
||||
You need to do this once per installed version.
|
||||
|
||||
### Uninstalling on macOS
|
||||
|
||||
Quit Lutra and drag **Lutra** from **Applications** to the Trash. Your data stays; delete the folders below to remove it.
|
||||
|
||||
## Where your data lives
|
||||
|
||||
| What | Windows | macOS |
|
||||
|---|---|---|
|
||||
| The app | `%LOCALAPPDATA%\Lutra\` | `/Applications/Lutra.app` |
|
||||
| Settings (`settings.json`), recovery journal (`recovery\`), downloaded Phpactor (`tools\`) | `%APPDATA%\com.tyrveil.lutra\` | `~/Library/Application Support/com.tyrveil.lutra/` |
|
||||
| Window data of the web view (recent projects, layout) | `%LOCALAPPDATA%\com.tyrveil.lutra\` | `~/Library/WebKit/com.tyrveil.lutra/`, `~/Library/Caches/com.tyrveil.lutra/` |
|
||||
|
||||
On Linux, when built from source: settings in `~/.config/com.tyrveil.lutra/`, journal and tools in `~/.local/share/com.tyrveil.lutra/`.
|
||||
|
||||
**From a build before the installers.** Earlier builds used the identifier `dev.lutra.desktop`. The first start of a new build copies `settings.json`, the recovery journal and the downloaded Phpactor from the old `dev.lutra.desktop` folders once and shows a notification; the old folders stay untouched and can be deleted afterwards. Recent projects and the window layout are not copied.
|
||||
|
||||
An instance started with `--control PORT` or `--data-dir DIR` keeps its files in its own folder (see [`development.md`](development.md#data-directories)).
|
||||
|
||||
## Revision history
|
||||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-31 | major | B1: initial version, NSIS setup and DMG, unsigned |
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
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)).
|
||||
Lutra is not signed or notarised yet. This guide builds it from source, 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
|
||||
|
||||
|
|
@ -177,6 +177,14 @@ The first time this asks for the Tauri CLI; install it with `cargo install tauri
|
|||
target/debug/lutra-desktop ~/Projekte/some-php-project
|
||||
```
|
||||
|
||||
## 9. Building the DMG
|
||||
|
||||
```sh
|
||||
cargo xtask bundle
|
||||
```
|
||||
|
||||
It builds the release app and packs it into `target/release/bundle/dmg/Lutra_<version>_aarch64.dmg` (the app itself is next to it in `target/release/bundle/macos/Lutra.app`). The DMG background comes in two sizes, joined with `tiffutil` so a Retina display shows the sharp one. A DMG you built yourself is not quarantined; one you copy to another Mac is, see [`install.md`](install.md#macos).
|
||||
|
||||
## 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.
|
||||
|
|
@ -188,7 +196,7 @@ target/debug/lutra-desktop ~/Projekte/some-php-project
|
|||
|
||||
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.
|
||||
- Real signing and notarisation need an Apple Developer ID; the alpha DMG is unsigned (owner decision D26), so the first start needs right-click ▸ Open or `xattr` (see [`install.md`](install.md#macos)).
|
||||
|
||||
## What is different on macOS
|
||||
|
||||
|
|
@ -196,7 +204,7 @@ target/debug/lutra-desktop ~/Projekte/some-php-project
|
|||
- **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.
|
||||
- **Data.** Settings, the recovery journal and the downloaded Phpactor live in `~/Library/Application Support/com.tyrveil.lutra/` (builds before the alpha installers used `dev.lutra.desktop/`; the first start copies its files over). 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
|
||||
|
|
@ -218,4 +226,5 @@ These can only be checked on the Mac itself, which is what the report does:
|
|||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-31 | minor | B1: new identifier `com.tyrveil.lutra`, building the DMG with `cargo xtask bundle` |
|
||||
| 2026-10-31 | major | A1: initial guide (setup, `cargo xtask mac-report`, Gatekeeper, macOS differences, what Windows cannot check) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue