- docs/macos.md: step-by-step setup for a fresh Apple Silicon Mac (Xcode CLT, Homebrew, git, PHP, Composer, Node 22, pnpm, rustup, clone from Forgejo), the machine report, Gatekeeper notes, macOS differences and what Windows cannot check. - cargo xtask mac-report: versions, the gate steps, the bundled-UI desktop build and a self-check over the control channel (project, file, Phpactor, hover, git.status, terminal, screenshot, quit); every step times out and runs in a lutra_proc group; one report.md to send back. - Fixes: macOS native menu (system menus only; Cmd+W stays buffer.close, Cmd+Q runs app.quit), xcap screenshot region in points on macOS (Retina), login shell (-l, /bin/zsh fallback) and LANG for the terminal on macOS, PHP lookup in Homebrew/MacPorts dirs for Finder starts, case-insensitive LSP path mapping on macOS, rendezvous file mode re-set to 0600, CLI-started desktop in its own process group. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
Gaps
Status: M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog with string and path controls, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover, definition, references and rename, Phpactor dies with Lutra, faster indexing, progress and messages,
php -lon Windows); G7 under way (lutraCLI and single instance, MCP server, integrated terminal); G8 under way (Git backend, M4.1; Changes window, M4.2; gutter markers and status colours, M4.4; diff viewer, M4.3; branch widget and popup, M4.5; merge conflicts, M4.8; remotes, M4.10; stash, M4.9); G14 English UI catalog in place · Last updated: 2026-10-26
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.
| # | Gap | Milestone | Estimate (one agent) |
|---|---|---|---|
| 2026-10-30 | patch | G8: stash (M4.9) | |
| 2026-10-30 | minor | New item: --control start can take the foreground; screenshot timeouts explained (F2b) |
|
| G1 | M0 | done (~2 h measured) | |
| G2 | Editor core: |
M1 | ~14 h |
| G3 | Project model: menuPaths; native macOS menu bar: A1 adds the system menus (Lutra, Edit, Window; ⌘W and ⌘Q stay Lutra's), mirroring Lutra's own menus natively and display modes open) |
M1 | ~24 h |
| G4 | Syntax and structure: tree-sitter PHP, --lt-syntax-* tokens; editor.reveal), syntax.outline), semantic highlighting, folding in the editor |
M2 | ~8 h |
| G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h |
| G6 | Language server: completion, definition, hover, rename via Phpactor ( |
M3 | ~15 h |
| G7 | lutra CLI and single instance--wait, forwarding a second start, token-protected rendezvous), lutra mcp with list/execute every command, screenshot, read buffer, recent events, open buffers as resources; still missing: resource and tool change notifications, progress for long commands), files outside the open project (the CLI refuses them; needs out-of-project buffers or a second window), lutra diff |
M3 | ~16 h |
| G8 | Git integration: gitChanged), git.merge, conflicts list, three-pane resolve view with accept left/right per chunk, mark resolved, abort; no ignore action, compare menu or rebase conflicts), |
M4 | ~122 h |
| G9 | Debugger, test runner, Composer, run configurations | M5 | ~300 h |
| G10 | Own indexer, type inference, inspections, refactorings | M6 | ~800 h |
| G11 | Stability: crash-free operation on real projects and machines ( |
ongoing | ~95 h |
| G12 | Performance budgets: start, open, type, search, index; command results without a deep copy (M2.7: syntax.outline holds the engine lock 82 ms on a 1 MB file because the stored JSON is copied into the result; a raw-JSON Outcome would avoid it) |
ongoing | ~101 h |
| G13 | Frameworks: Symfony, Laravel, Shopware, WordPress | M6 | ~300 h |
| G14 | Localization: English and German interface: EngineError.message) as message keys, language switch, plurals, German catalog |
later | ~38 h |
| G15 | Database tools, HTTP client, Docker and remote | later | ~430 h |
| G16 | Plug-ins and ecosystem | later | ~120 h |
| G17 | Deployment: servers (FTP, SFTP, local/mounted), path mappings, upload/download, compare with server, edit remote files, save before deploy, optional upload on save per server (owner wish 2026-10-18; needs credential storage and network access, §4) | M7 | ~120 h |
| G18 | Editor productivity: Local History, live and file templates, postfix completion, code generation, intention actions, auto import, scratch files, macros, compare files/folders, TODO view, language injections, code style/formatter | M6–M7 | ~400 h |
| G19 | Remote development and Dev Containers | M9 | ~200 h |
| G20 | AI features (chat, inline prompts, commit messages); MCP server is G7/M3 | M9 | ~60 h |
| G21 | Feature breadth: the full PhpStorm help inventory has 155 feature units; ~23 have at least partial support (2026-10-18, estimated). The list lives in plan/phpstorm/00-feature-inventory.md with public URLs |
ongoing | — |
G2 progress: the engine text buffer landed (M1.1, crates/text: rope, UTF-16 and char positions, atomic edit batches, line ending policy). M1.3 added engine buffers with versions, the edit protocol, save and save all, and reloading on external changes. M1.6 added tabs and a CodeMirror 6 editor synced to engine buffers (version-based edits with resync, CRLF-aware offsets), save and save all by engine shortcuts, the Save / Don't Save / Cancel question and a notice for files changed on disk. M1.7 added the crash-recovery journal (debounced atomic entries per dirty buffer, recovery.* commands, restore dialog; not yet checked in the running app). M1.13 made re-opening an open file switch to its tab and keeps the folders of open files watched. M3.10 added autosave (window blur, tab switch, after 15 s idle; settings) and flushDirty(), the one "save all dirty and wait" entry point for later deployment and run features; autosave skips files in conflict with the disk. Still open: tab management beyond open/close, a conflict UI (compare and merge with the disk version), local history, editor settings (soft wrap); estimate lowered to ~14 h.
G4 progress: M2.1 added the structural half in crates/syntax: tree-sitter PHP parse and incremental reparse, outline (namespaces, class-likes, functions, members, promoted properties, enum cases; anonymous classes marked) and folding ranges, an 8 MiB parse cap, proptests and snapshots. M2.2 made highlighting visible. M2.7 added the Structure tool window: each open PHP buffer keeps a tree-sitter tree, reparsed incrementally on a worker thread off the engine lock (200 ms debounce), syntax.outline and outlineChanged, and the outline as a tree in the left tool window with jumps through editor.reveal. Open in G4: semantic highlighting, folding in the editor, Structure speed search, sorting and filters. Finding: a full parse of 1 MB takes 364–553 ms on the dev machine (target 50 ms; reparse 7–11 ms), so parsing must stay off the engine lock and the index must parse in parallel.
G11 progress: M1.7 added the crash-recovery journal: unsaved buffers are written atomically about 1 s after the last edit and offered back after a crash; corrupt entries are skipped with a warning. Covered by a property test (random edits, crash, restore equals the buffer) and a headless control-channel test; not yet checked by killing the running app (gaming mode). Open: journal writes run under the engine lock (8.5 ms for 1 MiB, release), two instances on one project share a journal, local history.
G11 progress (H6): development and live-check instances no longer share the user's data. --data-dir PATH / LUTRA_DATA_DIR move settings, the recovery journal, the rendezvous file and the WebView2 user data (local storage) into one directory; --control PORT without either uses <temp>/lutra-control/<port>/. The Phpactor cache stays shared from the user's data directory. An isolated instance never forwards to or registers as the user's main instance. A unit test drives an isolated --control engine through the control channel (settings.set, journal write) and checks the user directory is byte-for-byte unchanged.
G11 progress (F3): Phpactor starts suspended and joins its kill-on-close job before its first instruction (lutra_proc::spawn_suspended); git and php -l keep the cheaper spawn (the suspended start costs about 60 ms more per process). The terminal's ConPTY shell is adopted into a job, so a dev server started in the terminal ends with the tab or with Lutra. A superseded completion request is cancelled with $/cancelRequest. The syntax undo round-trip proptest no longer fails on a wrapper node tree-sitter keeps after an incremental reparse (it compares leaf kinds, outline and folding). Not verified with a hard kill of the running app (Daniel at the PC).
G14 progress: M1.11 moved every UI string in ui/src into the English catalog ui/src/i18n/en.json behind t(key, params?), enforced by vue/no-bare-strings-in-template and a catalog test. Messages the engine sends (EngineError.message, the slogan from app.about) are still English text; they need message keys with params before a second language can cover them.
G5 progress: M2.3 landed the find-in-files backend: crates/search (parallel walk with the project's ignore rules, literal or regex, case, whole word, globs, binary and size skips, match cap, cancel) and the engine commands search.find / search.cancel with streamed searchResults and searchDone events; dirty buffers are searched in their buffer text. First result on a generated 20k-file tree 10–43 ms (release, measured). M2.4 added the Find tool window in a new bottom panel (options, globs, grouped and highlighted results, counts, cancel, truncated hint, keyboard navigation, editor.reveal, find.open Mod+Alt+F with prefill). M2.5 added the first symbol index (crates/index: every project file, PHP declarations from tree-sitter outlines, vendor as library, parallel build off the engine lock, incremental on disk and buffer changes, cancelled on project close) and the commands index.status, goto.file, goto.class, goto.symbol with indexProgress/indexReady events; a generated 20k-file project (88 MB of PHP) indexes in 3.9–4.2 s (release, measured, target 5 s), queries take 2–12 ms. M2.6 added the go-to popup (Files / Classes / Symbols tabs, Mod+P, Mod+Alt+C, Mod+T, live fuzzy results with marked characters, library rows labelled, indexing hint, editor.reveal). Open in G5: replace in files, scopes and history, go-to extras (recent files on an empty query, a non-project toggle, :line, file-type filter), an index that survives restarts, changes in directories the non-recursive watcher does not watch, usages.
Known smaller items from M0:
- The CI workflow has never run: the repository has no remote until the owner decides on hosting.
(F2, C6: WebView2ui.screenshotcaptures the screen region of the window and focuses itCapturePreviewon Windows, never focuses). macOS and Linux still capture the screen region (without focus), so covering windows appear there. A1 (C7) converts the region to points on macOS, whichxcapexpects there (it was off by the Retina scale); WKWebView's own snapshot would still be better.- A
--controlinstance started from the foreground app's process tree (an agent run from Claude) became the foreground window about 1 s after start 4 times on 2026-10-29/30, although window and webview are built withfocused(false). In 20 starts on 2026-10-30 (8 traced with an activation hook) it never happened, and nothing on Lutra's thread requested activation, so the cause is outside Lutra's code and intermittent. The ignored testscreenshot_focusguards it; the probe is in the C6 notes. Screenshots themselves do not take the foreground. A hidden page (locked session, display asleep) gives WebView2 no frames to capture; the error now says so. cargo xtask fixturesneeds Composer, which the M0 machine does not have.
G6 progress: M3.2 landed the LSP client library in crates/lsp: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), initialize with UTF-16 positions, typed requests with timeouts and $/cancelRequest, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from lutra_text edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, lspStatus) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see docs/architecture.md). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). M3.5 added go to definition (F12, Mod+click, a picker for several), find references (a References tab) and rename (F2, an inline field; open buffers dirty and undoable, closed files written atomically, edits outside the project refused), all through Phpactor without blocking the engine; rename has no preview list yet, and the editor's undo does not revert closed files it wrote. H1 (C5) put Phpactor into a kill-on-close group (crates/proc: a job object on Windows, a process group with a watchdog on Unix), so it no longer outlives Lutra, even when Lutra is killed. H3 (C5) made Phpactor on Windows useful sooner and more visible: a 1 ms tick while it indexes (a 2,000-class project gives a useful completion after 21–27 s instead of 72 s, measured), its progress in the status bar, its messages as notifications, and Lutra's own php -l for syntax errors on open and save. Still open: indexing is still bound by Phpactor's one-file-per-message loop (~110–190 files/s); superseded completion requests are not cancelled (Phpactor answers every list as incomplete, so it is asked on every keystroke; ~180 ms CPU per class-name request on 2,000 classes); quick-fixes.
Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-31 | patch | A1: macOS system menus (G3), Retina region for the macOS screenshot fallback |
| 2026-10-30 | patch | C6 review: the foreground-grab item is not reproduced in 20 starts; cause outside Lutra |
| 2026-10-28 | patch | G8: log and file history (M4.6) |
| 2026-10-28 | minor | G8 shrunk: remotes (M4.10) |
| 2026-10-27 | minor | G11 note: suspended Phpactor start, terminal shell in a job, completion cancel, syntax proptest (F3) |
| 2026-10-28 | minor | G8 shrunk: merge conflicts (M4.8) |
| 2026-10-27 | patch | G8: amend prefill, remote checkout fix, shared status store (C6 F1) |
| 2026-10-27 | minor | Screenshot item shrunk: webview capture without focus on Windows (F2) |
| 2026-10-26 | minor | G8 shrunk: branch widget and popup (M4.5) |
| 2026-10-26 | minor | G8 shrunk: diff viewer (M4.3) |
| 2026-10-25 | minor | G8 shrunk: gutter markers and status colours (M4.4) |
| 2026-10-25 | minor | G8 shrunk: Changes window (M4.2) |
| 2026-10-25 | minor | G8 shrunk: Git backend (M4.1) |
| 2026-10-24 | patch | G3/G6: string and path settings in the dialog, completion and tooltip settings (H4) |
| 2026-10-25 | minor | G11 note: isolated data directory for dev and live-check instances (H6) |
| 2026-10-25 | minor | G6 shrunk: faster indexing on Windows, progress and messages, php -l (H3) |
| 2026-10-24 | minor | G6: Phpactor no longer outlives Lutra (H1) |
| 2026-10-22 | minor | G6 shrunk: definition, references, rename (M3.5) |
| 2026-10-22 | minor | G6 shrunk: completion, hover and signature help (M3.4) |
| 2026-10-21 | minor | G6 shrunk: engine wiring and diagnostics (M3.3) |
| 2026-10-20 | minor | G2 shrunk: autosave and flushDirty (M3.10) |
| 2026-10-19 | minor | G7: MCP server (M3.8) |
| 2026-10-19 | minor | G3: app menu (M3.9) |
| 2026-10-18 | minor | G7: integrated terminal (M3.6), ~26 h → ~16 h |
| 2026-10-18 | minor | G6: PHP detection and pinned Phpactor download (M3.1) |
| 2026-10-18 | minor | G6: LSP client library (M3.2) |
| 2026-10-18 | minor | G17–G21 from the full PhpStorm inventory (deployment, editor productivity, remote, AI, breadth) |
| 2026-10-17 | minor | G7: lutra CLI and single instance (M3.7); out-of-project files and lutra diff listed |
| 2026-10-17 | minor | G5: go-to popup (M2.6) |
| 2026-10-17 | minor | G4: Structure tool window (M2.7); G12: raw-JSON command results |
| 2026-10-17 | minor | G5: symbol index and go-to commands (M2.5) |
| 2026-10-17 | minor | G5: Find tool window (M2.4) |
| 2026-10-16 | minor | G4: Lezer highlighting and editor.reveal (M2.2) |
| 2026-10-16 | minor | G5: find-in-files backend (M2.3) |
| 2026-10-16 | minor | G4 note: tree-sitter syntax library, outline and folding (M2.1) |
| 2026-10-16 | minor | G3: settings dialog, theme picker (M1.9b) |
| 2026-10-16 | minor | G3: command palette, global keymap, UI commands (M1.8) |
| 2026-10-16 | minor | G2/G3: re-open focuses the tab, open buffers' folders watched, truncated listings shown (M1.13) |
| 2026-10-15 | minor | G14 note: English message catalog (M1.11) |
| 2026-10-15 | minor | G2 shrunk: tabs and editor (M1.6) |
| 2026-10-16 | minor | G3: folder-picker error notifications (M1.12) |
| 2026-10-16 | minor | G2 shrunk, G11 note: recovery journal (M1.7) |
| 2026-10-16 | minor | G3: theme switching (M1.10) |
| 2026-10-16 | minor | G3: settings backend (M1.9a) |
| 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) |
| 2026-10-14 | minor | G3: native file watching (M1.2b); notify item resolved (CC0-1.0 approved for notify) |
| 2026-10-14 | minor | G3 shrunk by the VFS (M1.2); notify licence item |
| 2026-10-14 | minor | G1 closed; estimates for G2–G16; M0 follow-ups |
| 2026-10-13 | major | Initial gap list |