M0: import starter package (rules, roadmap, progress docs)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-13 20:22:22 +02:00
commit 1fc46daa8e
22 changed files with 790 additions and 0 deletions

44
docs/architecture.md Normal file
View file

@ -0,0 +1,44 @@
# Architecture
> **Status:** draft, to be completed in M0 · **Last updated:** 2026-10-13
## Overview
```
apps/lutra-desktop (L6) Tauri 2 shell: windows, menus, IPC bridge to the engine
ui/ (L6) Vue 3 + TypeScript + Vite frontend, Pinia, CodeMirror 6
apps/lutra-cli (L5) the `lutra` command: open, diff, --wait, mcp, perf, bench
crates/control (L5) JSON-lines control channel (--control PORT)
crates/mcp (L5) MCP server over stdio
crates/engine (L4) command registry, workspace state, guard, recovery journal
crates/lsp (L3) LSP client (Phpactor first), later DAP client
crates/index (L2) symbol index, usages, later type inference
crates/vfs (L2) project model, file watching, ignore rules, encodings
crates/search (L2) find in files (ignore + grep-searcher crates)
crates/syntax (L1) tree-sitter parsing (PHP first), outlines, highlight tokens
crates/text (L0) rope buffer, positions, UTF-8/UTF-16 conversion, edits
crates/testkit (—) test helpers and fixtures, tests only
xtask (—) ci, layers, assets, cleanroom, dev, fixtures
```
A crate may depend only on crates of a lower layer. `cargo xtask layers` checks it. Nothing below L6 depends on Tauri or the frontend.
## Commands
Every user-visible action is a command: `id`, `label`, `menu_path`, `default_shortcut`, `params` (documented schema), `enabled(&State) -> bool`, `run(&mut State, Params) -> Result<Output, EngineError>`. Menus, the palette, keymaps, the CLI, the control channel and MCP all call the registry. Long-running commands report progress and can be cancelled.
## Frontend ↔ engine
The frontend calls `run(id, params)` over Tauri IPC and subscribes to state events (open buffers, diagnostics, tree changes). Buffer contents live in the engine; CodeMirror sends edits as transactions and receives authoritative changes back. Theme tokens are defined in Rust and exported as CSS variables.
## Open questions for M0
- Highlighting: tree-sitter tokens from the core vs. a Lezer grammar in CodeMirror for instant highlighting (tree-sitter stays the structural source either way).
- Git library: `gix` (preferred, MIT/Apache) vs. alternatives.
- Terminal: `portable-pty` in the core, xterm.js in the frontend.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Initial draft |

32
docs/development.md Normal file
View file

@ -0,0 +1,32 @@
# Development
> **Status:** draft · **Last updated:** 2026-10-13
## Prerequisites
- Rust stable (via rustup), edition 2024
- Node.js 20 or newer and pnpm
- Tauri 2 system prerequisites for your platform (WebView2 on Windows, WebKitGTK on Linux)
- Optional: Phpactor on the PATH for language features, PHP 8.2+ and Composer for reference projects
## Everyday commands
```sh
cargo xtask dev # run the app in development mode
cargo xtask ci # the full quality gate, run before every commit
cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/
```
## Robustness: Lutra never crashes
Shipped code returns errors instead of panicking (see AGENTS.md › Never crash). The engine guard catches panics at every entry point, keeps buffers intact and reports an internal error. Unsaved buffers are journaled so a restart can restore them.
## Code style
No inline comments. Doc comment blocks above modules, functions, types and fields explain purpose, parameters, return values and errors.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Initial draft |

28
docs/framework-parity.md Normal file
View file

@ -0,0 +1,28 @@
# Framework checklist
> **Status:** baseline · **Last updated:** 2026-10-13
## Symfony
- [ ] Routes, services and container navigation
- [ ] Twig templates: highlighting, navigation, completion
- [ ] Console commands as run configurations
## Laravel
- [ ] Routes, facades, Eloquent model completion
- [ ] Blade templates
- [ ] Artisan commands
## Shopware 6
- [ ] Plugin structure, services.xml navigation
- [ ] Twig storefront templates with block inheritance
- [ ] Administration (Vue) snippets
## WordPress
- [ ] Hooks (actions and filters) navigation
- [ ] Plugin and theme scaffolding
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Baseline |

30
docs/gaps.md Normal file
View file

@ -0,0 +1,30 @@
# Gaps
> **Status:** initial list · **Last updated:** 2026-10-13
Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap.
| # | Gap | Milestone | Estimate (one agent) |
|---|---|---|---|
| G1 | Foundation: workspace, quality gate, command registry, guard, control channel | M0 | after M0 planning |
| G2 | Editor core: buffers, undo, multi-caret, save, recovery journal | M1 | — |
| G3 | Project model: VFS, file watching, project tree, tabs | M1 | — |
| G4 | Syntax and structure: tree-sitter PHP, highlighting, file structure | M2 | — |
| G5 | Search and navigation: find in files, go to file/class/symbol | M2 | — |
| G6 | Language server: completion, diagnostics, definition, hover, rename via Phpactor | M3 | — |
| G7 | Terminal and `lutra` CLI | M3 | — |
| G8 | Git integration | M4 | — |
| G9 | Debugger, test runner, Composer, run configurations | M5 | — |
| G10 | Own indexer, inspections, refactorings | M6 | — |
| G11 | Stability: crash-free operation on real projects and machines | ongoing | — |
| G12 | Performance budgets: start, open, type, search, index | ongoing | — |
| G13 | Frameworks: Symfony, Laravel, Shopware, WordPress | M6 | — |
| G14 | Localization: English and German interface | later | — |
| G15 | Database tools, HTTP client, Docker and remote | later | — |
| G16 | Plug-ins and ecosystem | later | — |
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Initial gap list |

21
docs/language-parity.md Normal file
View file

@ -0,0 +1,21 @@
# PHP language checklist
> **Status:** baseline · **Last updated:** 2026-10-13 · Reference: php.net and the PHP RFCs
- [ ] Parsing of PHP 8.0–8.4 syntax (attributes, match, enums, readonly, first-class callables, property hooks, asymmetric visibility)
- [ ] Highlighting, including heredoc/nowdoc and embedded HTML
- [ ] File structure: namespaces, classes, interfaces, traits, enums, functions, constants
- [ ] Go to declaration and implementation
- [ ] Find usages
- [ ] Completion: members, functions, classes with auto-import, keywords
- [ ] Type inference from declarations, PHPDoc, generics in PHPDoc
- [ ] Diagnostics: syntax errors, undefined symbols, type mismatches
- [ ] Refactorings: rename, extract variable/method, move class, change signature
- [ ] Formatting to PSR-12 / PER coding style
- [ ] PHPDoc generation and completion
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Baseline |

View file

@ -0,0 +1,16 @@
# Localization checklist
> **Status:** baseline · **Last updated:** 2026-10-13
| Language | Code | Status | Translated |
|---|---|---|---:|
| English | `en` | source | 0% |
| German | `de` | planned | 0% |
All interface strings go through the message catalog from the first UI task on; no hard-coded labels.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Baseline |

30
docs/roadmap.md Normal file
View file

@ -0,0 +1,30 @@
# Milestones
> **Status:** current focus M0 · **Last updated:** 2026-10-13
| Milestone | Goal | State |
|---|---|---|
| M0 | Foundation: workspace, lints, quality gate, command registry, control channel, empty window | not started |
| M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | not started |
| M2 | Syntax and search: highlighting, structure, find in files, go to file/class/symbol | not started |
| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI — **MVP** | not started |
| M4 | Git: status, diff, commit, branches, log, blame, conflicts | not started |
| M5 | Debugger (Xdebug via DAP), PHPUnit/Pest runner, Composer, run configurations | not started |
| M6 | Own indexer and inspections; Symfony, Laravel, Shopware, WordPress support | not started |
## Alpha gate
Alpha is reached when these six core workflows work end to end on macOS, Windows and Linux, with save and reopen:
1. Open a project, browse and edit files, save, recover after a crash.
2. Navigate: go to file, class, symbol and definition; find in files.
3. Write code with completion and diagnostics.
4. Run commands in the integrated terminal.
5. Commit, diff and switch branches with Git.
6. Drive all of the above from the CLI, the control channel and MCP.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Initial milestones |

42
docs/target-app-parity.md Normal file
View file

@ -0,0 +1,42 @@
# Target-app parity
> **Status:** baseline, nothing ships · **Last updated:** 2026-10-13 · **Target:** PhpStorm 2026.x
## How this is measured
Each feature area gets a weight (how much a typical PHP developer uses it) and a score (how much of the documented behaviour Lutra has, judged by behaviour, not by menu items). The headline depth is the weighted sum. Every score is marked measured or estimated and must point to evidence (tests, commands, screenshots of Lutra). Behaviour references come from public PhpStorm documentation only, noted with URLs in `plan/phpstorm/`.
## Feature areas
| Area | Weight | Score | Missing | Hours (one agent) | Evidence |
|---|---:|---:|---|---:|---|
| Editor core | 12 | 0% | everything | — | — |
| Project view, VFS | 6 | 0% | everything | — | — |
| Navigation | 10 | 0% | everything | — | — |
| Search and replace | 6 | 0% | everything | — | — |
| Code completion | 10 | 0% | everything | — | — |
| Inspections and quick-fixes | 8 | 0% | everything | — | — |
| Refactoring | 7 | 0% | everything | — | — |
| Code style and formatting | 4 | 0% | everything | — | — |
| Git | 8 | 0% | everything | — | — |
| Terminal | 3 | 0% | everything | — | — |
| Run configurations | 2 | 0% | everything | — | — |
| Debugger | 5 | 0% | everything | — | — |
| Testing | 4 | 0% | everything | — | — |
| Composer and interpreters | 2 | 0% | everything | — | — |
| Frameworks | 5 | 0% | everything | — | — |
| Database tools | 3 | 0% | everything | — | — |
| HTTP client | 1 | 0% | everything | — | — |
| Web languages | 2 | 0% | everything | — | — |
| Docker and remote | 1 | 0% | everything | — | — |
| Settings, keymaps, themes | 1 | 0% | everything | — | — |
| Plug-ins | 0.5 | 0% | everything | — | — |
| AI features | 0.5 | 0% | everything | — | — |
Weights are a first estimate and are reviewed at the end of M0.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Baseline |

20
docs/tooling-parity.md Normal file
View file

@ -0,0 +1,20 @@
# Tooling checklist
> **Status:** baseline · **Last updated:** 2026-10-13
- [ ] Integrated terminal with tabs
- [ ] Git: status, diff, commit, push/pull, branches, log, blame, conflict resolution
- [ ] Composer: install, update, require, scripts
- [ ] PHP interpreters: local, Docker
- [ ] Xdebug via DAP: breakpoints, stepping, variables, watches
- [ ] PHPUnit and Pest: run, rerun failed, coverage
- [ ] PHPStan, Psalm, PHP-CS-Fixer integration
- [ ] Run configurations
- [ ] Database tools: connect, browse, query console
- [ ] HTTP client
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Baseline |

23
docs/ui-parity.md Normal file
View file

@ -0,0 +1,23 @@
# UI parity checklist
> **Status:** baseline · **Last updated:** 2026-10-13
- [ ] Main window: tool window stripes, editor area, status bar, navigation bar
- [ ] Project tool window (tree, scroll from source, file operations)
- [ ] Editor tabs (pin, split, reorder, close others)
- [ ] Command palette / search everywhere
- [ ] Settings dialog with search
- [ ] Keymap editor (Lutra's own default keymap; no copied keymaps)
- [ ] Light and dark themes from theme tokens
- [ ] Notifications and background task indicator
- [ ] Structure tool window
- [ ] Problems tool window
- [ ] Find tool window
- [ ] Terminal tool window
- [ ] Git tool window
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | major | Baseline |