Lutra/AGENTS.md
danny 07adedadbd M0.6: allow Unicode-3.0 (owner decision)
unicode-ident (via serde, thiserror, syn) and the ICU4X crates pulled in
by Tauri are under Unicode-3.0. The owner approved adding it to the
permissive list; AGENTS.md, deny.toml, the frontend licence check and
NOTICE are updated. Restores a green cargo xtask ci.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 06:44:52 +02:00

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

  1. Read ROADMAP.md (stage, numbers by dimension, what's next) and the ranked work list in 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. 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). 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 (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 (@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 (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.

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 run -p lutra-desktop -- --control 7979 [path] starts it with the JSON control channel. 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

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.