Lutra/docs/development.md
danny 13c42ccc40 A2: alpha acceptance checklist and cargo xtask demo-project
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>
2026-10-31 20:53:03 +01:00

70 lines
4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`](macos.md)
## Everyday commands
```sh
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`](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:
```sh
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_DIR` inside the repository folder: the default `target/`, or `<worktree>/target` per 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_DIR` and 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:
```sh
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 |