Engine (`cmd/lsp_nav.rs`, on the pending outcomes of 20d1d28):
- `lsp.definition` (F12) and `lsp.references` (Shift+F12, sorted, with
line previews) return project-relative locations; locations outside
the project, such as PHAR stubs and symlink escapes, are dropped.
- `lsp.prepareRename` uses the word at the cursor when the server has
no prepareProvider.
- `lsp.rename` (F2) applies the workspace edit (`lsp_nav/edit.rs`):
1. Check everything first: inside the project, ranges fit (UTF-16,
CRLF), open buffers unchanged since the request, no file
operations, no incomplete edit.
2. Write closed files atomically through the VFS, restoring earlier
writes when a later one fails.
3. Change open buffers through `buffer.edit` (dirty, undoable).
4. Send each written file to Phpactor as didOpen/didSave/didClose
plus didChangeWatchedFiles; without this its index kept the old
names. Then the summary notification `notification.lsp.renamed`.
UI (`components/editor/nav/`):
- Mod+click goes to the definition, with a pointer cursor while Mod is
held.
- A location picker for several definitions (exclusive modal).
- A References tab in the bottom panel, grouped by file.
- An inline rename field with a use/file count (exclusive modal).
- `BufferSync.beginUndoableRemote` puts the engine's rename edit into
the editor history as one undo step per buffer.
- Catalog strings and tokens only.
Fake LSP server: `--script FILE` with scripted capabilities and
answers (additive next to M3.4's arms).
Tests:
- `crates/engine/tests/lsp_nav.rs` (fake): definition; bad positions;
references; prepareRename; a multi-file rename incl. a closed CRLF
file; refusals for outside the project, a bad range, a stale buffer,
bad names and no server.
- The ignored real-Phpactor test covers definition, references and a
rename and back across 3 files.
- Vitest `ui/tests/nav/`.
Live (Phpactor 2026.06.25.0, Windows, port 7935, tick on):
- definition 93 ms cold / 7-18 ms warm
- references ~140 ms
- prepareRename ~11 ms
- rename 28-59 ms
- index follows written files in 140 ms
- Phpactor 57 MB working set, ~1.6% of a core while ticking idle
Gate: 13 steps, 197 s, Vitest 484 + 1 skipped.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
82 lines
5 KiB
Markdown
82 lines
5 KiB
Markdown
<p align="center">
|
||
<img alt="Lutra — an otterly perfect IDE" src="docs/images/banner.png" width="100%">
|
||
</p>
|
||
|
||
<h1 align="center">Lutra</h1>
|
||
|
||
<p align="center">
|
||
A fast, open-source, clean-room PHP IDE in the spirit of the PhpStorm workflow.
|
||
Rust core, Vue interface, native on macOS, Windows and Linux.
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img alt="Status: pre-alpha" src="https://img.shields.io/badge/status-pre--alpha-8a6a4f">
|
||
<img alt="Core in Rust" src="https://img.shields.io/badge/core-Rust-b83a24?logo=rust&logoColor=white">
|
||
<img alt="UI in Vue" src="https://img.shields.io/badge/UI-Vue%203-42b883?logo=vuedotjs&logoColor=white">
|
||
<img alt="Runs on macOS, Windows and Linux" src="https://img.shields.io/badge/runs%20on-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-555555">
|
||
<img alt="MCP server for agents" src="https://img.shields.io/badge/agents-MCP%20server-555555">
|
||
<img alt="License: MIT OR Apache-2.0" src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-555555">
|
||
</p>
|
||
|
||
> *Lutra* is the Latin name of the otter. Sea otters are among the few animals that use tools:
|
||
> they crack shells open with a stone. Lutra is that stone for your PHP code.
|
||
|
||
## Why Lutra
|
||
|
||
- **Familiar.** Project view, tool windows, Search Everywhere-style navigation, Go to Class, Find Usages, refactorings: the workflow PHP developers already know.
|
||
- **Fast.** A Rust core with an incremental index, search off the UI thread and a lightweight Tauri shell.
|
||
- **Robust.** No panics in shipped code, a crash-recovery journal for unsaved buffers, property-tested protocols.
|
||
- **Open.** MIT OR Apache-2.0, no account, no telemetry.
|
||
- **Agent-native.** Every action is a command that a JSON control channel and an MCP server expose, so Claude and other agents can work in the IDE the way a person does.
|
||
- **PHP-first.** Symfony, Laravel, Shopware and WordPress support are on the roadmap from the start.
|
||
|
||
## Quick start
|
||
|
||
> The foundation (M0) is built: `cargo xtask dev` opens an empty themed window and `cargo xtask ci` runs the quality gate. The `lutra` command below is the target of milestone M3.
|
||
|
||
```sh
|
||
git clone <repo-url> lutra
|
||
cd lutra
|
||
|
||
cargo xtask dev # desktop app in development mode
|
||
cargo xtask dev -- --control 7979 . # + JSON control channel
|
||
cargo xtask ci # fmt, clippy, tests, layers, assets, clean-room, frontend checks
|
||
```
|
||
|
||
### The `lutra` command
|
||
|
||
Works today (M3.7): opening folders and files (at a line) in the running Lutra or starting it, and `--wait`. The rest arrives with M3 and later.
|
||
|
||
```sh
|
||
lutra . # open the current folder as a project
|
||
lutra src/Kernel.php:42 # open a file at a line
|
||
lutra diff a.php b.php # open the diff viewer
|
||
lutra --wait FILE # wait until the tab is closed (git config core.editor "lutra --wait")
|
||
lutra mcp # MCP server on stdio
|
||
lutra perf # check the performance budgets
|
||
```
|
||
|
||
### Use it from Claude Code
|
||
|
||
```sh
|
||
claude mcp add lutra -- lutra mcp
|
||
```
|
||
|
||
## Status
|
||
|
||
**Pre-alpha (2026-10-17): M2 done.** You can open a folder, browse it in the project tree with live updates from disk, and edit and save files in tabs with syntax highlighting for PHP (and HTML, CSS, JS/TS, JSON, YAML, Markdown), with every command in a palette (`Mod+Shift+P`) and settings and the light or dark theme in a settings dialog (`Mod+,`); unsaved text survives a crash and is offered back on the next open; M2 added find in files (`Mod+Alt+F`) and go to file, class or symbol (`Mod+P`, `Mod+Alt+C`, `Mod+T`); M3 has begun with an integrated terminal (`Mod+Shift+T`) and PHP language features from Phpactor: errors underlined as you type (Problems tab `Mod+Alt+P`), code completion, documentation on hover and parameter info, go to definition (`F12` or Ctrl+click), find references (`Shift+F12`) and rename (`F2`). About 12 agent hours remain to the MVP (M3: language server, terminal, CLI and MCP). [**ROADMAP.md**](ROADMAP.md) has the stage and what's next,
|
||
[`docs/target-app-parity.md`](docs/target-app-parity.md) the parity assessment and [`docs/gaps.md`](docs/gaps.md) the ranked work list.
|
||
|
||
**First target (MVP, M1–M3):** open a project, project tree, tabs, editor with highlighting, find in files,
|
||
go to definition, completion and diagnostics via a language server, command palette, integrated terminal,
|
||
the `lutra` CLI, light and dark themes.
|
||
|
||
Agent and contributor rules (clean-room, asset policy, no panics, quality gates) are in [`AGENTS.md`](AGENTS.md).
|
||
Every bundled asset is listed with its licence in [`ASSETS.md`](ASSETS.md).
|
||
|
||
## License
|
||
|
||
Lutra is dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.
|
||
Copyright (c) 2026 Daniel Diekert and the Lutra contributors. Required notices are in [NOTICE](NOTICE).
|
||
|
||
<sub>PhpStorm, IntelliJ IDEA and JetBrains are trademarks or registered trademarks of JetBrains s.r.o. Lutra is an independent, open-source project and is not affiliated with, sponsored by or endorsed by JetBrains s.r.o.; these names are used only to describe the workflows it is compatible with.</sub>
|