Lutra/README.md
danny a212a44490 M3.4: completion, hover and signature help from Phpactor
Engine (crates/engine/src/cmd/lsp_assist.rs), on M3.5's pending outcomes:
- lsp.completion {id, position, triggerCharacter?}: items with label,
  kind, detail, Markdown documentation, insertText, textEdit,
  additionalTextEdits, sortText; sorted, capped at 500 (cut lists are
  incomplete), snippets turned into plain text.
- lsp.hover {id, position}: Markdown contents and range.
- lsp.signatureHelp {id, position}: signatures with UTF-16 parameter spans.
- The request is queued after every didChange; the answer is converted
  in the reply callback, off the engine lock. Positions are checked
  against the buffer. Server strings and lists are capped.
- lutra-lsp-fake answers completion and signature help.

Editor (ui/src/components/editor/assist/):
- Completion source with Lutra's triggers (identifiers, $, ->, ?->, ::,
  namespace \; not in strings or comments unless asked), the server's
  ranking as boost, text edits and imports applied in UTF-16 (CRLF too),
  Lucide kind icons.
- Hover documentation (350 ms) and editor.quickDocumentation (Mod+I).
- Signature help on ( and , following the cursor; editor.parameterInfo.
- editor.complete.
- Lutra's own Markdown renderer without HTML (XSS-tested), tokens only.
- Requests wait for the buffer sync to be idle and use runWaiting.
- New dependency @codemirror/autocomplete (MIT, already transitive).

Tests: 6 engine tests against the fake server, 9 unit tests, an ignored
real-Phpactor latency test, 29 Vitest tests; palette and menu tests list
the new UI commands.

Measured with the real Phpactor (Windows 11, debug build, 25 ms tick):
- Completion 61-109 ms while typing (median 76 ms; ~107 ms in the app).
- Hover and signature help ~16 ms median.
- A useful list 2.3 s after opening a file in a 20-class project, ~65 s
  for 2,000 classes (indexing).
- Phpactor 56-71 MB working set, ~6% of one core while typing.

Live-checked in the app on port 7934. Docs: Code completion 0% -> 5%
(est.), feature depth ~4.1% -> ~4.6%, breadth 26/155, architecture, G6,
ui-parity, language-parity, roadmap, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 18:38:07 +02:00

82 lines
5 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.

<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 and rename come next. 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>