The window is built in setup with the theme tokens injected by an initialization script and the background colour taken from the theme, so the first frame is already themed. Frontend IPC (engine_execute, engine_list_commands) and the control channel both run commands through the Host, which applies effects such as Quit. ui.screenshot captures the window's client area from the screen because xcap skips windows of its own process. build.rs generates the placeholder icon into the gitignored icons/ directory. Verified on Windows: window opens, ping, listCommands, screenshot, app.quit, and exit status 1 when the control port is taken. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
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
- Read
ROADMAP.md(stage, numbers by dimension, what's next) and the ranked work list indocs/gaps.md. Unless the user gives you a task, pick work from that list. - Read
plan/STATUS.md(local session notes, may lag the ROADMAP), then the task inplan/execution-plan.md§3 and the relevant section ofdocs/architecture.md. Behaviour reference: public documentation only (see Clean-room below);plan/phpstorm/*.mdholds notes from it, each with source URLs. - 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 bycargo 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).
cargo denyand 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(path, author, source URL, licence, notes). Put licence texts next to the assets and summarise them inNOTICE.cargo xtask assets(run bycargo 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 inassets/icons/with the prefixlt-, and get anASSETS.mdrow. - Fonts come from npm packages (
@fontsource/inter,@fontsource/jetbrains-mono, OFL-1.1); never commit font files. - 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(orOption); callers handle it or propagate it with?. Failures reach the user as an error message (EngineErrorfor commands, the crate's own error type below the engine), never as an abort. - Workspace clippy lints ban these outside tests, so
cargo xtask cifails 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 ofv[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::guardis 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 replaceResult.- Unsaved buffers are written to a crash-recovery journal; a restart offers to restore them.
- Frontend: TypeScript
strict, noanywithout 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.
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,
rustfmtdefaults. 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 devstarts the desktop app in development mode (Vite + Tauri).cargo xtask dev -- --control 7979 [path]starts it with the JSON control channel. A plaincargo run -p lutra-desktop -- --control 7979works too whilepnpm --dir ui devruns; for a self-contained build runpnpm --dir ui buildand 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 inplan/phpstorm/. If no frame can be presented (headless machine), cover the component with a Vitest + Vue Test Utils test. - Performance:
lutra perfchecks 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 PATHtimes 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 fixturesintotarget/fixtures/(never committed). - Parallel agents: separate
CARGO_TARGET_DIRper agent; edit only the crates you own; delete your target dir when you finish.
Roadmap and progress docs
ROADMAP.md: stage, headline numbers, dimensions, features, upcoming, progress log.docs/target-app-parity.md: the authoritative parity assessment (area table, methodology, evidence of what ships).docs/gaps.md: every known shortfall, ranked; the work list.docs/roadmap.md: milestones and current focus.- Checklists:
ui-parity.md,language-parity.md,framework-parity.md,tooling-parity.md,localization-parity.md;architecture.md,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.