docs/alpha-checklist.md turns the six alpha workflows into manual steps for Windows and macOS (action, expected result, a box per platform, about 40 minutes each) and says how to report a failure. cargo xtask demo-project DIR creates the offline demo the steps run against: a small PHP shop (classes, an interface, a function, one deliberate error), a history by three authors from 2024 to 2026 with a merged branch and a tag, the branch feature/discounts that conflicts with main, and a bare origin.git holding a remote-only branch and one commit the project has not fetched yet. Tested against real git. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4 KiB
Development
Status: draft · Last updated: 2026-10-31
Prerequisites
- Rust stable (via rustup), edition 2024
- 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
Everyday commands
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
cargo xtask demo-project ../lutra-demo # offline demo project for docs/alpha-checklist.md
mac-report is made for checking a machine the developers cannot reach (the Mac, see 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:
cargo run -p lutra-desktop -- --control 7979 --data-dir target/lutra-data .
Delete the folder to start fresh. Its window opens without taking the foreground, and ui.screenshot never focuses it; only app.focus does. To check that on Windows, build with --features bundled-ui and run LUTRA_DESKTOP_EXE=<target>/debug/lutra-desktop.exe LUTRA_CONTROL_PORT=<port> cargo test -p lutra-desktop --test screenshot_focus -- --ignored.
Build directories and parallel work
- Keep
CARGO_TARGET_DIRinside the repository folder: the defaulttarget/, or<worktree>/targetper git worktree (/target/is gitignored). Antivirus exclusions usually cover the checkout. On Windows, unsigned binaries built outside an excluded folder have taken about 26 s to start each child process (Phpactor, git, the test helpers) against 28 ms inside, which makes tests time out. - Several builds in parallel (agents, worktrees): give each its own
CARGO_TARGET_DIRand limit the jobs, e.g.CARGO_BUILD_JOBS=4. Delete a worktree's target directory once its work is merged; a full build takes about 10 GB.
Deleting ui/node_modules
pnpm hardlinks packages from its shared store. Deleting ui/node_modules with Git Bash rm -rf on Windows breaks those links for other checkouts and makes their running Vitest fail with EBUSY. Delete it with either of:
cmd //c "rmdir /s /q ui\node_modules"
node -e "require('fs').rmSync('ui/node_modules',{recursive:true,force:true})"
Then run pnpm --dir ui install again.
Robustness: Lutra never crashes
Shipped code returns errors instead of panicking (see AGENTS.md › Never crash). The engine guard catches panics at every entry point, keeps buffers intact and reports an internal error. Unsaved buffers are journaled so a restart can restore them.
Code style
No inline comments. Doc comment blocks above modules, functions, types and fields explain purpose, parameters, return values and errors.
Revision history
| Date | Change | Summary |
|---|---|---|
| 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 |
| 2026-10-27 | minor | Unfocused --control windows and the screenshot focus check (F2) |
| 2026-10-25 | minor | Isolated data directory for --control instances (H6) |
| 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain |
| 2026-10-13 | major | Initial draft |