PM: merge H4 string and path settings controls, live assist settings
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 13:20:26 +01:00
commit e969f6497c
19 changed files with 1149 additions and 41 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1) · **Last updated:** 2026-10-24
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4) · **Last updated:** 2026-10-24
## Overview
@ -168,7 +168,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- `<config_dir>/settings.json`, a flat JSON object of dotted keys, written with `lutra_vfs::write_atomic` on every change. Unknown keys are kept; a stored value that fails validation counts as unset. Read with a 1 MiB cap.
- A file that is not a JSON object (invalid JSON, not UTF-8, too large) is renamed to `settings.json.bad-<YYYYMMDDTHHMMSSZ>` (with `-n` if taken), the defaults are used and a `notification {level: "warning", messageKey: "notification.settings.corrupt", message, params: {reason, backup}}` is queued. If it cannot be moved, or the directory or file cannot be read, settings stay in memory for the session (`notification.settings.corruptNotMoved`, `notification.settings.unavailable`) so the file is never overwritten.
- Keys: `appearance.theme` (`lutra-dark|lutra-light|system`, default `system`), `editor.fontSize` (int 8–48, default 14), `ui.language` (`en`), the autosave keys `editor.autosave.onBlur`, `editor.autosave.onTabSwitch` (bool, default true) and `editor.autosave.idleSeconds` (int 0–600, default 15; M3.10). Defined in `lutra_engine::settings::DEFS`.
- Keys: `appearance.theme` (`lutra-dark|lutra-light|system`, default `system`), `editor.fontSize` (int 8–48, default 14), `ui.language` (`en`), the autosave keys `editor.autosave.onBlur`, `editor.autosave.onTabSwitch` (bool, default true) and `editor.autosave.idleSeconds` (int 0–600, default 15; M3.10), the assist keys `editor.completion.autoPopup` (bool, default true), `editor.completion.delayMs` (int 0–2000, default 0) and `editor.hover.delayMs` (int 100–3000, default 350; H4). Defined in `lutra_engine::settings::DEFS`.
- Commands: `settings.list` → `[{key, type: enum|int, default, enumValues?, min?, max?, labelKey, descriptionKey, section}]` (catalog keys `settings.<key>.label` / `.description`; `section` is an id shown with `settings.section.<id>`), `settings.get {keys?}` → `{values}`, `settings.set {key, value}` → `{value}`, `settings.reset {key}` → `{value}`. Unknown keys and bad values fail with `invalid_params`; a write failure fails with `failed` and changes nothing.
- Events: `settingsChanged {keys}` when an effective value changes; `notification {id, level: info|warning|error, messageKey?, message?, params?}` (ids `n1`, `n2`…).
@ -248,7 +248,8 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **Store:** `ui/src/stores/settings.ts` (Pinia `settings`, started by `App.vue`) loads `settings.list` and `settings.get`, reads both defensively (unknown types and malformed entries dropped, values must be scalars), changes values through `settings.set`/`settings.reset` and keeps a refused change's message per key. `settingsChanged` reloads the named keys with `settings.get {keys}` and drops their errors, so changes from the control channel or an agent show at once.
- **Text:** labels, descriptions and section names come from the catalog keys the engine sends (`settings.<key>.label`, `.description`, `settings.section.<id>`); enum values use `settings.<key>.value.<value in camelCase>`. A key the catalog lacks shows the setting key (or the raw value). These keys are in the catalog test's runtime list.
- **Font size:** `theme.ts` has `setTokenOverride(name, value)`: a value above the theme's that `applyTheme` keeps across theme switches. The store sets `--lt-font-size-editor` to `editor.fontSize` px; the editor reads only that token.
- **Dialog:** `ui/src/components/settings/SettingsDialog.vue` (mounted in `App.vue`) provides `settings.open` (`Mod+,`, palette, `uiCommand`). Sections on the left, the chosen section's settings on the right; enum → select, int → number field (min/max, applied when committed; text that is no whole number in range is refused in place with `settings.error.intRange`), bool → switch. The theme picker is the `appearance.theme` select; the engine answers with `themeChanged`.
- **Dialog:** `ui/src/components/settings/SettingsDialog.vue` (mounted in `App.vue`) provides `settings.open` (`Mod+,`, palette, `uiCommand`). Sections on the left, the chosen section's settings on the right; enum → select, int → number field (min/max, applied when committed; text that is no whole number in range is refused in place with `settings.error.intRange`), bool → switch, string → text field (H4). The theme picker is the `appearance.theme` select; the engine answers with `themeChanged`.
- **String and path settings (H4, `stringSetting.ts`):** every `string` setting from `settings.list` gets a text field, applied when committed, so a new key (M4.1's `git.executable`) needs no UI change. A string setting whose key's last segment ends in `path` or `executable` is a path: it gets "Browse…", which calls the desktop's `pick_file {title}` IPC (the dialog plugin's native file picker, run off the main thread; `ipc.ts › pickFile`) and applies the chosen file through `settings.set`; a path with an empty default shows "Detected automatically" while empty. Checks before `settings.set`, each with its own catalog message: at most 4,096 UTF-8 bytes and no control characters (every string), no surrounding quotes and no spaces at either end (paths). The engine validates everything else. String rows stack the field under the label at full width. `settings.open {section?, query?}` opens on a section or with a search (for agents and live checks).
- **Search** matches label, description, key and section name (every word, ignoring case); while it has text every match shows, grouped by section, and sections without matches are dimmed.
- **Reset to default** per setting, enabled while the value differs from the default.
- **Errors** show under the control (`role="alert"`, `aria-invalid`) and keep the typed text until the value changes.
@ -459,7 +460,8 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- The server's order becomes the boost. A complete list is filtered locally while typing; an incomplete one is asked again on each keystroke.
- Applying an item uses its `textEdit` (else replaces the typed word with `insertText`) and its `additionalTextEdits` in one transaction. Text typed after the request is accounted for, and overlapping imports are skipped.
- The kind icon is a Lucide component rendered into the list row.
- **Hover:** `hoverTooltip` after 350 ms; `editor.quickDocumentation` (`Mod+I`) shows the same tooltip at the cursor.
- **Hover:** `hoverTooltip` after `editor.hover.delayMs` (default 350 ms); `editor.quickDocumentation` (`Mod+I`) shows the same tooltip at the cursor.
- **Settings (H4, `assist/settings.ts`):** `editor.completion.autoPopup` (typing opens the list; the shortcut always does), `editor.completion.delayMs` (CodeMirror's `activateOnTypingDelay`) and `editor.hover.delayMs` (`hoverTime`), read from the settings store (defaults without a Pinia, numbers clamped to the engine's ranges). Completion and hover sit in compartments; a view plugin follows the store and reconfigures every open PHP editor when a value changes, and a state field remembers the values a state was built with, so a state shown again later catches up. A reconfiguration recreates the hover extension, which closes an open hover tooltip.
- **Signature help:**
- A state field holds the tooltip; a view plugin asks on `(` and `,`, and while open on every edit or cursor move (120 ms debounce), dropping stale answers.
- `Escape` closes it, `Mod-Shift-Space` and `editor.parameterInfo` open it.
@ -523,7 +525,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **HTTP client:** `ureq` 3 with `rustls` (the `ring` provider) and the operating system's trusted roots loaded with `rustls-native-certs` (Windows store, macOS keychain, Linux files or `SSL_CERT_FILE`). `rustls-platform-verifier` and ureq's default `webpki-roots` were rejected: both pull a CDLA-Permissive-2.0 crate (`webpki-root-certs` / `webpki-roots`), outside the licence allow list. Proxies come from `HTTPS_PROXY`/`ALL_PROXY`/`NO_PROXY`. Timeouts: 15 s connect, 300 s per attempt.
- **Download:** `download::install` reads the body into memory with a cap of 32 MiB (Content-Length checked first, then the bytes read), compares its SHA-256 with the pin and only then writes `<data_dir>/tools/phpactor/<version>/phpactor.phar` with `lutra_vfs::write_atomic`. A mismatch discards the body and leaves an existing file untouched; nothing unverified ever lies at the target path. `install_with_retry` retries network errors, 5xx, 408 and 429 up to 4 attempts with 2 s, 4 s, 8 s backoff; a mismatch, an oversized body and other client errors are final. A managed PHAR that no longer matches its hash counts as missing and is downloaded again.
- **PHP detection:** `php::detect` resolves the setting (a path, or a bare name looked up in `PATH`; empty means `php`, on Windows `php.exe`, `php.bat`, `php.cmd`), runs `php -v` without a console window, with a 5 s timeout (killed after it) and at most 64 KiB of output read, and parses the first line starting with `PHP <major>.<minor>[.<patch>]` (suffixes such as `-dev` or `-1ubuntu1` are ignored; property-tested with random bytes).
- **Engine:** settings `php.executable` (string, default `""`), `phpactor.path` (string, default `""`) and `phpactor.autoDownload` (bool, default `true`), section `php`; `settings.list` now has the types `bool` and `string` (the settings dialog shows bool switches; a text control for string settings is a UI follow-up). One worker thread (`lutra-toolchain`) runs checks and the download; commands and the pump only queue jobs (merged while it works, the strongest mode wins), and its reports reach the state through `Engine::pump_vfs` (`cmd::toolchain::pump`), like search results. Jobs start with the first `toolchain.status`, when a project opens (a download if the project has PHP files: a root `composer.json` or a `.php`/`.phtml`/`.inc` file within 6 levels, at most 20,000 entries, skipping `vendor`, `node_modules`, hidden and cache directories; PHP is usable; Phpactor is missing; auto-download is on), when one of the three settings changes after the first check, and with `toolchain.downloadPhpactor` (also with auto-download off; `failed` if the host allows no downloads).
- **Engine:** settings `php.executable` (string, default `""`), `phpactor.path` (string, default `""`) and `phpactor.autoDownload` (bool, default `true`), section `php`; `settings.list` now has the types `bool` and `string` (the settings dialog shows bool switches, and since H4 a text field with "Browse…" for the two paths). One worker thread (`lutra-toolchain`) runs checks and the download; commands and the pump only queue jobs (merged while it works, the strongest mode wins), and its reports reach the state through `Engine::pump_vfs` (`cmd::toolchain::pump`), like search results. Jobs start with the first `toolchain.status`, when a project opens (a download if the project has PHP files: a root `composer.json` or a `.php`/`.phtml`/`.inc` file within 6 levels, at most 20,000 entries, skipping `vendor`, `node_modules`, hidden and cache directories; PHP is usable; Phpactor is missing; auto-download is on), when one of the three settings changes after the first check, and with `toolchain.downloadPhpactor` (also with auto-download off; `failed` if the host allows no downloads).
- **Commands and event:** `toolchain.status` → `{php: {found, path, version, error?}, phpactor: {state: missing|downloading|ready|failed|disabled, path?, version?, error?}}` as last checked (the first call starts a check); `toolchain.downloadPhpactor` → `{started}`; event `toolchainChanged` with the same shape whenever it changes. A `phpactor.path` PHAR is ready if it is a file, with no version and no hash check (the user chose it).
- **Notifications:** `notification.toolchain.phpMissing {reason, min}` (warning, when the PHP result changes to unusable), `notification.toolchain.downloadStarted {version}` and `notification.toolchain.downloadDone {version, seconds}` (info), `notification.toolchain.downloadFailed {version, reason}` (error).
- **Live check** (debug build, bundled UI, port 7931, Windows 11, PHP 8.4.24 from WinGet, a temp project with one PHP file, empty data directory): `project.open` → PHP found after 0.15 s, `downloadStarted` after 0.35 s, the real download from GitHub plus SHA-256 check took 2.8 s (notification to notification, measured), `toolchain.status` then `ready` with `<data_dir>/tools/phpactor/2026.06.25.0/phpactor.phar`, whose hash on disk equals the pin. A second run through `toolchain.downloadPhpactor` after deleting the PHAR took 0.3 s; both toasts showed in the window.
@ -557,6 +559,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-24 | minor | H4: string and path controls in the settings dialog (`pick_file` IPC), assist settings (auto popup, completion delay, hover delay) read live |
| 2026-10-25 | minor | H6: isolated data directory (`--data-dir`, `LUTRA_DATA_DIR`, `--control` temp dir), shared tools dir, rendezvous order |
| 2026-10-24 | minor | H1: `crates/proc` (L0), child processes in kill-on-close groups (Windows job objects, Unix process groups with a watchdog); Phpactor and the PHP probe use it |
| 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) |