M1.4: desktop bridge: engine events to the window, folder picker, live project tree

The desktop host publishes every engine event, from commands and from a
pump thread that calls Engine::pump_vfs every 100 ms, to control channel
subscribers and to the window as the Tauri event engine://event, in engine
order. ui/src/ipc.ts gets a typed onEngineEvent; its first subscription
calls engine_ready, and the host replays the current project and buffers,
so a project opened from the command line (lutra-desktop --control PORT
PATH) reaches the UI. project.openDialog returns Effect::PickFolder; the
host shows the native folder picker (tauri-plugin-dialog, licence checked)
and opens the choice, one picker at a time, cancel is not an error.
Capabilities shrink to event listen/unlisten.

Contract fix: the M1.5 project UI assumed shapes the engine does not use.
engineEvents.ts now translates engine events ({kind: projectOpened, ...})
and project.children results ({dir, entries, truncated}) into the UI types,
keeping role and truncated; the store maps listings through
toTreeEntries() and the project tests use the real engine shapes.

Verified in the running app on Windows 11: tree of a project given on the
command line, expanding src, a file created on disk appearing live, the
folder picker opening one dialog and opening the chosen folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-15 06:41:49 +02:00
parent 69130d1efb
commit dd98636de4
23 changed files with 751 additions and 99 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded · **Last updated:** 2026-10-14
> **Status:** M0 decisions recorded, M1 workspace and desktop bridge documented · **Last updated:** 2026-10-15
## Overview
@ -80,10 +80,18 @@ Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS cus
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`. Events say what changed; clients fetch data with `project.children` and `buffer.get`.
Changes on disk reach the engine through `Engine::pump_vfs()`, which hosts call regularly (the desktop's pump thread arrives with M1.4; tests call it directly). It maps VFS events to `treeChanged` for the parent directories, reloads a clean buffer whose file changed (unless the file already matches, as after our own save) with `bufferChanged`, and reports `fileChangedOnDisk` for a dirty buffer, which keeps its text, or for a removed file. At most 10,000 VFS events are handled per pump.
Changes on disk reach the engine through `Engine::pump_vfs()`, which hosts call regularly (the desktop's pump thread every 100 ms; tests call it directly). It maps VFS events to `treeChanged` for the parent directories, reloads a clean buffer whose file changed (unless the file already matches, as after our own save) with `bufferChanged`, and reports `fileChangedOnDisk` for a dirty buffer, which keeps its text, or for a removed file. At most 10,000 VFS events are handled per pump.
Watched directories: the VFS watcher is non-recursive, so `project.children` watches each directory it lists. At most 256 directories besides the root are watched natively and 32 when polling (each polled directory is rescanned every 100 ms); beyond that the least recently listed directory is unwatched, and listing it again re-watches it. Expanding a deep `vendor/` therefore costs at most 256 native watches; changes in directories that dropped out are not reported until they are listed again. `node_modules`, ignored and hidden directories are never watched.
### Desktop bridge (M1.4)
- The desktop host publishes every event, from commands and from its pump thread, to control channel subscribers and to the window as the Tauri event `engine://event` with the engine `Event` as payload. Events are published while the engine lock is held, so their order is the engine's order.
- `ui/src/ipc.ts` exposes `onEngineEvent(handler) => unsubscribe` with the typed union `EngineEventPayload`. The first successful subscription calls the IPC command `engine_ready`; the host then replays `projectOpened` and `bufferOpened` for the current state to the window only. A project opened from the command line (`lutra-desktop --control 7979 PATH`) or before a page reload therefore still reaches the UI.
- `project.openDialog` returns `Effect::PickFolder`; the host shows the native folder picker (`tauri-plugin-dialog`, from Rust, non-blocking) and runs `project.open` with the choice. At most one picker is open; cancelling does nothing. A folder that cannot be opened (for example `unsaved_changes`) is only logged to stderr until the UI can show notifications.
- Capabilities: the main window may only listen to and unlisten from events (`core:event:allow-listen`, `core:event:allow-unlisten`). Engine commands are app commands and need no permission; the dialog plugin is used from Rust only, so the frontend gets no dialog permission.
- Contract fix: the project UI from M1.5 was written against assumed shapes. `ui/src/components/project/engineEvents.ts` is now the adapter between the engine contract and the UI types: `toProjectEvent` translates `{kind: "projectOpened", root, name}` and friends into the store's events, and `toTreeEntries` translates `project.children`'s `{dir, entries: [{name, path, kind: file|directory|other, ignored, role}], truncated}` into tree entries (`kind: dir|file`, `role`, `excluded`, `special` for `other`) plus `truncated`. Malformed entries are skipped; a result without `entries` becomes an `ipc` error on the directory.
## Decisions (M0)
| Question | Decision | Why |
@ -101,6 +109,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-15 | minor | M1.4: desktop bridge (engine://event, engine_ready replay, folder picker, capabilities), UI contract fix |
| 2026-10-14 | minor | M1.3: workspace commands, edit protocol, events, events.subscribe, watched-directory limits |
| 2026-10-14 | minor | Screenshot method, placeholder app identifier |
| 2026-10-13 | major | M0: layers metadata, command and guard design, control protocol, open questions decided |

View file

@ -1,6 +1,6 @@
# Gaps
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers) · **Last updated:** 2026-10-14
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers); G3 project tree works in the app · **Last updated:** 2026-10-15
Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated.
@ -8,7 +8,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t
|---|---|---|---|
| G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) |
| G2 | Editor core: ~~engine buffers, save~~ (M1.3), editor UI, undo, multi-caret, recovery journal | M1 | ~25 h |
| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), project tree (UI exists against a mocked engine, M1.5; engine side with `project.children` and tree events landed in M1.3; wiring in M1.4), tabs; command palette, settings, theme switching | M1 | ~27 h |
| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, showing truncated listings, error notifications for the folder picker, tabs; command palette, settings, theme switching | M1 | ~24 h |
| G4 | Syntax and structure: tree-sitter PHP, Lezer highlighting, file structure | M2 | ~15 h |
| G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h |
| G6 | Language server: completion, diagnostics, definition, hover, rename via Phpactor | M3 | ~45 h |
@ -35,6 +35,7 @@ Known smaller items from M0:
| Date | Change | Summary |
|---|---|---|
| 2026-10-15 | minor | G3 shrunk: project tree wired to the engine (M1.4) |
| 2026-10-14 | minor | G2 shrunk, G3 note: engine workspace (M1.3) |
| 2026-10-14 | minor | G3 note: project tree UI (M1.5) |
| 2026-10-14 | minor | G2 note: text buffer landed (M1.1) |

View file

@ -1,13 +1,13 @@
# Milestones
> **Status:** M0 done, M1 in progress · **Last updated:** 2026-10-14
> **Status:** M0 done, M1 in progress · **Last updated:** 2026-10-15
Hours are agent wall-clock hours for one agent; M0 is measured, the rest estimated.
| Milestone | Goal | State | Hours |
|---|---|---|---:|
| M0 | Foundation: workspace, lints, quality gate, command registry, control channel, empty window | done 2026-10-14 (CI workflow written, not yet run: no remote) | ~2 (measured) |
| M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | in progress (M1.1 text, M1.2 VFS, M1.5 tree UI, M1.3 engine workspace) | ~60 |
| M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | in progress (M1.1 text, M1.2 VFS, M1.5 tree UI, M1.3 engine workspace, M1.4 desktop bridge) | ~60 |
| M2 | Syntax and search: highlighting, structure, find in files, go to file/class/symbol | not started | ~50 |
| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | not started | ~80 |
| M4 | Git: status, diff, commit, branches, log, blame, conflicts | not started | ~150 |
@ -31,6 +31,7 @@ By the estimates above the alpha gate needs M1–M4 plus cross-platform verifica
| Date | Change | Summary |
|---|---|---|
| 2026-10-15 | minor | M1.4 desktop bridge |
| 2026-10-14 | minor | M1 in progress |
| 2026-10-14 | minor | M0 done; hours per milestone |
| 2026-10-13 | major | Initial milestones |

View file

@ -1,6 +1,6 @@
# Target-app parity
> **Status:** M1 in progress (text buffer, VFS, tree UI, engine workspace landed), no PHP feature ships · **Last updated:** 2026-10-14 · **Target:** PhpStorm 2026.x
> **Status:** M1 in progress (text buffer, VFS, engine workspace, project tree in the app), no PHP feature ships · **Last updated:** 2026-10-15 · **Target:** PhpStorm 2026.x
## How this is measured
@ -13,7 +13,7 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour
| Area | Weight | Score | Missing | Hours (one agent) | Evidence |
|---|---:|---:|---|---:|---|
| Editor core | 12 | 0% | everything user-visible: no editor in the UI yet; engine buffers, file commands and events exist | ~120 (est.) | `crates/text`: rope buffer, positions, edits (M1.1, unit tests + proptests). M1.3: engine buffers with versions and dirty state, `file.open`, `buffer.get`, `buffer.edit` (UTF-16 change sets, `stale_version`), `file.save`, `file.saveAll`, `buffer.close` with unsaved-changes guard, line ending and BOM kept on save, clean buffers reload on external change; 14 integration tests on temp dirs (`crates/engine/tests/workspace.rs`) |
| Project view, VFS | 6 | 0% | everything reachable in the app: the tree UI is not wired to the engine yet (M1.4) | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`). M1.5: project tree UI (lazy listing, keyboard navigation, dimmed ignored entries, event refresh) in `ui/src/components/project/`, Vitest against a mocked engine. M1.3: `project.open`, `project.close`, `project.children` (watches listed directories, capped at 256 native / 32 polling, least recently listed dropped), `treeChanged` events from disk, `events.subscribe` on the control channel with a TCP test (`crates/control/tests/events.rs`) |
| Project view, VFS | 6 | 8% (est.) | views list (project / scopes), toolbar (Select Opened File, Expand/Collapse All), sort and display options, show/hide excluded, distinct icons for library and excluded folders, file colours, speed search, preview, file operations, showing truncated listings | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`). M1.5: project tree UI (lazy listing, keyboard navigation, dimmed ignored entries, event refresh) in `ui/src/components/project/`, Vitest against a mocked engine. M1.3: `project.open`, `project.close`, `project.children` (watches listed directories, capped at 256 native / 32 polling, least recently listed dropped), `treeChanged` events from disk, `events.subscribe` on the control channel with a TCP test (`crates/control/tests/events.rs`). M1.4: the tree runs against the engine in the app: folder picker (`project.openDialog`) and `lutra-desktop --control PORT PATH` open a project, the tree lists it lazily with ignored (`var/` from `.gitignore`) and excluded (`node_modules`) entries dimmed, a file created on disk appears in an expanded folder within ~100 ms; verified with `ui.screenshot` on Windows 11 and Vitest (`ui/tests/project/`, `ui/tests/ipcEvents.test.ts`). Graded against `plan/phpstorm/02-project-view.md`: tool window, folder-first tree, dimmed ignored/excluded, keyboard navigation and live refresh exist; most toolbar, view and display options do not |
| Navigation | 10 | 0% | everything | ~120 (est.) | — |
| Search and replace | 6 | 0% | everything | ~80 (est.) | — |
| Code completion | 10 | 0% | everything | ~250 (est.) | — |
@ -50,7 +50,7 @@ No PHP feature. The foundation, verified on Windows 11:
## What ships (M1, in progress)
Nothing user-visible yet, so every score stays 0%.
The project tree is the first user-visible feature (Project view 8%, estimated); every other score stays 0%.
- M1.1 text buffer (`crates/text`): `Buffer` on a `ropey` rope with byte, char, UTF-16 and line counts; byte offset to line and column in UTF-16 code units or chars and back, all fallible (out of range, inside a character, inside a CRLF, inside a surrogate pair); atomic `Edit` batches in LSP `TextEdit[]` semantics that reject reversed, out-of-range and overlapping ranges; `
` / `
@ -61,6 +61,7 @@ Nothing user-visible yet, so every score stays 0%.
| Date | Change | Summary |
|---|---|---|
| 2026-10-15 | minor | Project view 0% → 8% (estimated): tree runs against the engine in the app (M1.4) |
| 2026-10-14 | minor | Project view evidence: project tree UI (M1.5), score unchanged |
| 2026-10-14 | minor | M1.3 engine workspace evidence (Editor core, Project view; scores unchanged) |
| 2026-10-14 | minor | M1.1 text buffer evidence (Editor core, score unchanged) |

View file

@ -1,11 +1,12 @@
# UI parity checklist
> **Status:** main window layout and project tree against a mocked engine (M1.5) · **Last updated:** 2026-10-14
> **Status:** main window layout and project tree against a mocked engine (M1.5) · **Last updated:** 2026-10-15
- [ ] Main window: tool window stripes, editor area, status bar, navigation bar
- M1.5 (2026-10-14): left tool window with header, hide button, collapsed stripe with a show button, resizable by pointer and keyboard; editor area placeholder; status bar. Missing: stripes with several tool windows, bottom/right docking, navigation bar, layout persistence. Not checked in the running app yet (needs M1.4).
- [ ] Project tool window (tree, scroll from source, file operations)
- M1.5 (2026-10-14): tree of the open folder with lazy `project.children` listings, folders and PHP files with Lucide icons, ignored/excluded entries dimmed, keyboard navigation (WAI-ARIA tree: arrows, Home/End, Enter), double-click opens, refresh on `TreeChanged`, listing errors shown in the tree, empty state with Open Folder…. Vitest only, against a mocked engine. Missing: scroll from source (Select Opened File), expand/collapse all, views list, sort options, speed search, file colours, file operations. Behaviour notes: `plan/phpstorm/02-project-view.md`.
- M1.5 (2026-10-14): tree of the open folder with lazy `project.children` listings, folders and PHP files with Lucide icons, ignored/excluded entries dimmed, keyboard navigation (WAI-ARIA tree: arrows, Home/End, Enter), double-click opens, refresh on `TreeChanged`, listing errors shown in the tree, empty state with Open Folder…. Vitest only, against a mocked engine.
- M1.4 (2026-10-15): runs against the real engine in the app: projects open from the folder picker or the command line, the tree updates live when files change on disk; checked with `ui.screenshot` on Windows 11. Missing: scroll from source (Select Opened File), expand/collapse all, views list, sort options, speed search, file colours, file operations. Behaviour notes: `plan/phpstorm/02-project-view.md`.
- [ ] Editor tabs (pin, split, reorder, close others)
- [ ] Command palette / search everywhere
- [ ] Settings dialog with search
@ -22,5 +23,6 @@
| Date | Change | Summary |
|---|---|---|
| 2026-10-15 | minor | Project tool window runs against the engine (M1.4) |
| 2026-10-14 | minor | Notes on main window and project tool window (M1.5) |
| 2026-10-13 | major | Baseline |