commit 1fc46daa8ebf0426e266e1bfe2f9bbd30562faa8 Author: danny Date: Tue Oct 13 20:22:22 2026 +0200 M0: import starter package (rules, roadmap, progress docs) Co-Authored-By: Claude Opus 5.5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2f1fbb2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +/plan/ +/target/ +/target-*/ +node_modules/ +dist/ +.DS_Store +*.log +.idea/ +.vscode/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..196f6e4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# 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). `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 (`@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`](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 `