87 lines
12 KiB
Markdown
87 lines
12 KiB
Markdown
# Lutra — instructions for agents
|
|
|
|
Lutra ("An otterly perfect IDE") is a clean-room, open-source PHP IDE targeting the workflow of JetBrains PhpStorm (and beyond). The core is Rust; the desktop app is Tauri 2 with a Vue 3 + TypeScript frontend. It runs on macOS, Windows and Linux. The name is the Latin genus of the otter (*Lutra lutra*); sea otters use tools, and that is our motif.
|
|
|
|
## Start every session here
|
|
1. Read [`ROADMAP.md`](ROADMAP.md) (stage, numbers by dimension, what's next) and the ranked work list in [`docs/gaps.md`](docs/gaps.md). Unless the user gives you a task, pick work from that list.
|
|
2. Read `plan/STATUS.md` (local session notes, may lag the ROADMAP), then the task in `plan/execution-plan.md` §3 and the relevant section of [`docs/architecture.md`](docs/architecture.md). Behaviour reference: public documentation only (see Clean-room below); `plan/phpstorm/*.md` holds notes from it, each with source URLs.
|
|
3. Follow the autonomous operation protocol (`plan/execution-plan.md` §7): orient → plan → implement + test → verify → record → commit. Don't stop to ask unless §4 of the execution plan lists the decision as the owner's.
|
|
|
|
`plan/` is gitignored (local only).
|
|
|
|
## Non-negotiables
|
|
|
|
### Clean-room: never use JetBrains software as a reference (absolute rule, from the project owner)
|
|
- Never launch, run, script, automate, screenshot or measure PhpStorm, IntelliJ IDEA or any other JetBrains IDE, and never compare Lutra's output against one. Don't create test files or fixtures with them.
|
|
- Never read, decompile or copy anything inside a JetBrains install (JARs, plugins, bundled schemes, keymap XML, inspection descriptions, templates, icons, fonts shipped inside the IDE, help files).
|
|
- Never copy JetBrains-authored code or text into this repo, tests included. This also covers JetBrains' open-source code (intellij-community, its plugins, its inspection texts): we stay clean-room even where a licence would allow copying.
|
|
- Behaviour comes only from public documentation (jetbrains.com/help, public blog posts, public issue trackers and forum posts), cited by URL in `plan/phpstorm/`, and from the PHP language itself (php.net, the PHP RFCs, PSR specifications).
|
|
- Feature names may be used to describe behaviour ("Go to Class", "Find Usages"). Wording, icons, colour schemes and default keymaps are not copied; Lutra ships its own.
|
|
- If a task seems to need any of this, stop and say so instead. `cargo xtask cleanroom` (run by `cargo xtask ci`) fails on JetBrains copyright notices and on files that look like exported JetBrains configuration.
|
|
- Never copy GPL/AGPL/LGPL code. Dependencies must be under a permissive licence (MIT, Apache-2.0, BSD, ISC, Zlib, MPL-2.0 as a separate crate/package only; Unicode-3.0, approved by the owner on 2026-10-14 for unicode-ident and the ICU4X crates; CC0-1.0 for the notify crate only, approved by the owner on 2026-10-14). `cargo deny` and the frontend licence check enforce it.
|
|
|
|
### Assets: no JetBrains iconography or images, ever (absolute rule, from the project owner)
|
|
- Never add, copy, trace, redraw from, embed or ship any icon, image, cursor, colour scheme, keymap, live template, file template or screenshot from JetBrains products or from any source whose licence doesn't allow it.
|
|
- Every image, icon, font or other asset must be one of:
|
|
- original work created for Lutra by a contributor (who licenses it MIT OR Apache-2.0);
|
|
- OSI open source;
|
|
- public domain / CC0;
|
|
- Creative Commons with redistribution allowed.
|
|
- **Every asset file must have a row in [`ASSETS.md`](ASSETS.md)** (path, author, source URL, licence, notes). Put licence texts next to the assets and summarise them in `NOTICE`. `cargo xtask assets` (run by `cargo xtask ci`) fails on any unattributed asset.
|
|
- UI icons come from Lucide (`lucide-vue-next`, ISC). Icons Lutra needs that Lucide lacks (PHP class, interface, trait, enum, attribute…) are drawn for Lutra, live in `assets/icons/` with the prefix `lt-`, and get an `ASSETS.md` row.
|
|
- Fonts come from npm packages; never commit font files. The only bundled font is IBM Plex Mono (`@fontsource/ibm-plex-mono`, OFL-1.1, owner decision D28) for the editor and the terminal; the UI uses the system font.
|
|
- Prefer art generated in code for defaults (colour schemes, file-type badges). If the provenance of an asset is unclear, don't add it.
|
|
- The app icon (an otter holding a stone) is the owner's to commission or approve. Until then the build uses a placeholder generated in code.
|
|
|
|
### Never crash: no panics in shipped code
|
|
A crash loses the user's unsaved work. Files on disk, project contents, LSP and DAP messages, terminal output, control and MCP messages, and command params are all untrusted input.
|
|
- Fallible work returns `Result` (or `Option`); callers handle it or propagate it with `?`. Failures reach the user as an error message (`EngineError` for commands, the crate's own error type below the engine), never as an abort.
|
|
- Workspace clippy lints ban these outside tests, so `cargo xtask ci` fails on them: `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`, `unimplemented!`. Use `?`, `.ok_or(…)?`, `let … else { return … }`, `if let`, `unwrap_or*`, `.first()` / `.last()` / `.get()`, and a real error for a match arm you believe is impossible.
|
|
- Don't panic implicitly either: use `.get(i)` instead of `v[i]` or `&s[a..b]` when the index comes from data. Text offsets are byte offsets on UTF-8 boundaries; convert through the text crate's helpers, never by hand. Cap sizes and counts read from input (file sizes, LSP payloads, search results).
|
|
- Don't silence errors just to satisfy the lint. Where ignoring a failure is right (`let _ =`, `.ok()`), say why in the doc comment of the enclosing function.
|
|
- Tests may unwrap and panic (`#[test]`, `#[cfg(test)]`, `tests/`, `testkit`).
|
|
- `lutra_engine::guard` is the last line of defence: every entry point (commands, IPC from the frontend, control and MCP requests, LSP/DAP callbacks) catches a panic, keeps open buffers intact and reports an internal error. It exists for bugs and doesn't replace `Result`.
|
|
- Unsaved buffers are written to a crash-recovery journal; a restart offers to restore them.
|
|
- Frontend: TypeScript `strict`, no `any` without a reason in the doc comment, no unhandled promise rejections (lint rule), every IPC call handles its error.
|
|
- Untrusted input is fuzzed or property-tested (file decoding, the control protocol, LSP message parsing, command params). Extend those tests when you add a parser or a protocol method.
|
|
|
|
### Everything is a command
|
|
User-visible behaviour = a command in `crates/engine/src/cmd/*` (id, label, menu path, default shortcut, params doc, `enabled`, `run`) + tests. Menus, the command palette, shortcuts, the `lutra` CLI, the control channel and MCP all reach the same commands. UI-only commands (focus a tool window, toggle a panel) are registered by the frontend in `ui/src/commands/` and are still listed in the registry so the palette, keymap editor and agents see them.
|
|
|
|
### Layering
|
|
Enforced by `cargo xtask layers`. Nothing below L6 depends on Tauri or the frontend. See [`docs/architecture.md`](docs/architecture.md).
|
|
|
|
### The UI is thin
|
|
Vue components read engine state (pushed as events) and act through `run(commandId, params)`. Colours come from theme tokens (CSS variables generated from the Rust theme definition), never hard-coded.
|
|
|
|
### Code style
|
|
- Code, identifiers, commits and docs in English.
|
|
- **No inline comments in code.** Explain intent with doc comment blocks above modules, functions, structs, enums and their fields: purpose, parameters, return value, errors (`///` and `//!` in Rust, TSDoc `/** … */` in TypeScript and Vue `<script setup>`).
|
|
- Rust: edition 2024, `rustfmt` defaults. Vue: Composition API with `<script setup lang="ts">`, Pinia for state, pnpm as package manager.
|
|
|
|
### Quality gates before every commit
|
|
`cargo xtask ci` runs: `cargo fmt --check`, `cargo clippy --workspace -- -D warnings` (including the no-panic lints), `cargo test --workspace`, `cargo xtask layers`, `cargo xtask assets`, `cargo xtask cleanroom`, `cargo deny check licenses`, and in `ui/`: `pnpm lint`, `pnpm typecheck` (vue-tsc), `pnpm test` (Vitest). One task id per commit (`M1.3: project tree`).
|
|
|
|
## Running and looking at the app
|
|
- `cargo xtask dev` starts the desktop app in development mode (Vite + Tauri).
|
|
- `cargo xtask dev -- --control 7979 [path]` starts it with the JSON control channel. A plain `cargo run -p lutra-desktop -- --control 7979` works too while `pnpm --dir ui dev` runs; for a self-contained build run `pnpm --dir ui build` and add `--features bundled-ui`. If the port is taken, the app exits with an error; pick another port.
|
|
- Drive it with JSON lines on `127.0.0.1:7979`, e.g. `{"id":1,"method":"engine.execute","params":{"command":"project.open","params":{"path":"/tmp/demo"}}}` then `{"id":2,"method":"ui.screenshot","params":{"path":"/tmp/shot.png"}}`. Methods: `crates/control/src/methods.rs`.
|
|
- **For UI work, look at the result**: take `ui.screenshot`, read the PNG, and compare it with the public documentation notes in `plan/phpstorm/`. If no frame can be presented (headless machine), cover the component with a Vitest + Vue Test Utils test.
|
|
- **Performance:** `lutra perf` checks the budgets (cold start, open a 1 MB file, keystroke to highlight, find in files, index a reference project) on generated and reference projects; `lutra bench PATH` times one project. Run them before and after editor, index or search changes, on an idle machine.
|
|
- MCP: `lutra mcp` (stdio). Register with Claude Code: `claude mcp add lutra -- lutra mcp`.
|
|
- Reference projects for tests and perf: fresh Symfony and Laravel skeletons, created by `cargo xtask fixtures` into `target/fixtures/` (never committed).
|
|
- Parallel agents: separate `CARGO_TARGET_DIR` per agent; edit only the crates you own; delete your target dir when you finish.
|
|
|
|
## Roadmap and progress docs
|
|
- [`ROADMAP.md`](ROADMAP.md): stage, headline numbers, dimensions, features, upcoming, progress log.
|
|
- [`docs/target-app-parity.md`](docs/target-app-parity.md): the authoritative parity assessment (area table, methodology, evidence of what ships).
|
|
- [`docs/gaps.md`](docs/gaps.md): every known shortfall, ranked; the work list. [`docs/roadmap.md`](docs/roadmap.md): milestones and current focus.
|
|
- Checklists: [`ui-parity.md`](docs/ui-parity.md), [`language-parity.md`](docs/language-parity.md), [`framework-parity.md`](docs/framework-parity.md), [`tooling-parity.md`](docs/tooling-parity.md), [`localization-parity.md`](docs/localization-parity.md); [`architecture.md`](docs/architecture.md), [`development.md`](docs/development.md).
|
|
|
|
When a task lands, update in the same commit: the area row in `docs/target-app-parity.md` (score, missing items, hours) and its evidence, the gap entry in `docs/gaps.md` if it closed or shrank, the checklist it belongs to, the milestone row in `docs/roadmap.md`, and the ROADMAP's tables and progress log when a headline number moves. Update each touched doc's status line and revision history.
|
|
- Grade by behaviour against the public documentation, not by whether a menu item exists. Scores are self-assessed, so err low; mark each number measured or estimated.
|
|
- Keep the README's Status section in step with the ROADMAP headline.
|
|
|
|
## Contributor credits (About window)
|
|
- About ▸ Contributors is compiled from `contributors/people.toml` (names people chose for themselves) and git history.
|
|
- When you prepare a PR for a human contributor whose username has no entry, ask them once whether they want to be credited by more than their username. If yes, add **only their own** entry. Never add, edit, guess or copy anyone else's name.
|