diff --git a/README.md b/README.md index afdf680..28ee92b 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ claude mcp add lutra -- lutra mcp ## Status -**Pre-alpha (2026-10-16): M1 in progress.** You can open a folder, browse it in the project tree with live updates from disk, and edit and save files in tabs (plain text for now), with every command in a palette (`Mod+Shift+P`); unsaved text survives a crash and is offered back on the next open; syntax highlighting and PHP features come next. The MVP (M1–M3) is estimated at about 20 agent hours after calibrating on the first cycle (2.5 h done). [**ROADMAP.md**](ROADMAP.md) has the stage and what's next, +**Pre-alpha (2026-10-16): M1 done.** You can open a folder, browse it in the project tree with live updates from disk, and edit and save files in tabs (plain text for now), with every command in a palette (`Mod+Shift+P`) and settings and the light or dark theme in a settings dialog (`Mod+,`); unsaved text survives a crash and is offered back on the next open; syntax highlighting and PHP features come next. With M1 done, about 13 agent hours remain to the MVP (M2 and M3, estimated after calibrating on the first cycle). [**ROADMAP.md**](ROADMAP.md) has the stage and what's next, [`docs/target-app-parity.md`](docs/target-app-parity.md) the parity assessment and [`docs/gaps.md`](docs/gaps.md) the ranked work list. **First target (MVP, M1–M3):** open a project, project tree, tabs, editor with highlighting, find in files, diff --git a/ROADMAP.md b/ROADMAP.md index b728f78..36b75f6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,20 +1,20 @@ # Lutra Roadmap -**Stage: pre-alpha (M1 in progress)** · next: the rest of M1 (settings dialog), then M2 syntax and search; alpha when the six core workflows work end to end (see [docs/roadmap.md › Alpha gate](docs/roadmap.md#alpha-gate)) +**Stage: pre-alpha (M1 done)** · next: M2 syntax and search; alpha when the six core workflows work end to end (see [docs/roadmap.md › Alpha gate](docs/roadmap.md#alpha-gate)) -> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-16 · **Change:** minor (M1.8: command palette and keymap) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only +> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-16 · **Change:** minor (M1.9b: settings dialog; M1 done) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only Lutra is a clean-room, open-source PHP IDE with a Rust core and a Tauri + Vue interface, targeting the PhpStorm workflow. Agents can drive all of it over MCP, the `lutra` CLI and a JSON control channel. This page is the summary; the evidence is in [`docs/target-app-parity.md`](docs/target-app-parity.md) and the work list in [`docs/gaps.md`](docs/gaps.md). -**Why pre-alpha:** M0 built the foundation (workspace, quality gate, command registry with panic guard, control channel, a themed window). M1 so far lets you open a folder, browse it in the project tree and edit and save files in tabs, but as plain text: no PHP feature (highlighting, completion, navigation) exists yet. M1–M3 deliver the MVP. +**Why pre-alpha:** M0 built the foundation (workspace, quality gate, command registry with panic guard, control channel, a themed window). M1 lets you open a folder, browse it in the project tree, edit and save files in tabs, get unsaved text back after a crash, run every command from a palette and change settings and the theme in a settings dialog, but as plain text: no PHP feature (highlighting, completion, navigation) exists yet. M1–M3 deliver the MVP. ## Headline numbers | | Value | Kind | |---|---|---| | **Feature breadth** (PhpStorm's actions, tool windows, languages, integrations exist) | **<1%** (project tool window, editor tabs; no inventory to count against yet) | estimated | -| **Feature depth** (weighted by use, scored by behaviour) | **~1.6%** (Editor core 9% × weight 12, Project view 8% × weight 6, Settings 4% × weight 1, of 101) | estimated | -| **To MVP (M3)** | **~20 h** (M1 ~6 h of which 2.5 h done, M2 ~5 h, M3 ~8 h); was ~190 h before calibration | estimated (×0.1 from cycle C1) | +| **Feature depth** (weighted by use, scored by behaviour) | **~1.6%** (Editor core 9% × weight 12, Project view 8% × weight 6, Settings 7% × weight 1, of 101) | estimated | +| **To MVP (M3)** | **~13 h left** (M1 done: C1 2.5 h measured, C2 time in the cycle review; M2 ~5 h, M3 ~8 h); was ~190 h before calibration | estimated (×0.1 from cycle C1) | | **To full parity** | **~330 h** if cycle C1's speed holds (range 300–3,300 h; deep areas such as type inference and inspections have no data yet) | estimated | Hours are agent wall-clock hours for one agent. M0 took about 2 h of active agent time (measured from the session, excluding toolchain installation and waiting for owner decisions). Later milestones are estimated far more conservatively per line of code, because editor, language and UI work need integration, debugging and visual checks that the foundation did not. Estimates are recalibrated after each cycle from task start times and commit timestamps. Cycle C1 (M1.1–M1.6) took 2.5 h of agent time for 37 h estimated (factor 0.07); M1–M3 hours are scaled by ×0.1 since then, and the per-area hours below are the raw first estimates (multiply by ~0.1 for the calibrated value). PhpStorm is **not** inspected: the clean-room rule in [`AGENTS.md`](AGENTS.md) forbids it, so everything is measured from our code against public documentation. @@ -60,7 +60,7 @@ Stability 8%: no-panic lints, the engine guard, a fuzzed control protocol and a | HTTP client | 0% | ~60 | | Web languages (JS/TS, Vue, CSS, Twig, Blade) | 0% | ~200 | | Docker and remote | 0% | ~120 | -| Settings, keymaps, themes | 4% (est.) | ~60 | +| Settings, keymaps, themes | 7% (est.) | ~60 | | Plug-ins and ecosystem | 0% | ~120 | | AI features | 0% | ~60 | @@ -68,15 +68,15 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a ## Upcoming -1. **M1 editor and project (~6 h, 2.5 h done):** open folder, project tree, tabs, editor, save and recovery, command palette, settings, themes. -2. **M2 syntax and search (~5 h):** highlighting, file structure, find in files, go to file/class/symbol. -3. **M3 language server, terminal and CLI (~8 h):** completion, diagnostics, go to definition via Phpactor; terminal; `lutra` CLI and MCP. **MVP.** -4. **Then:** Git (M4), debugger, tests and Composer (M5), own indexer and frameworks (M6). +1. **M2 syntax and search (~5 h):** highlighting, file structure, find in files, go to file/class/symbol. +2. **M3 language server, terminal and CLI (~8 h):** completion, diagnostics, go to definition via Phpactor; terminal; `lutra` CLI and MCP. **MVP.** +3. **Then:** Git (M4), debugger, tests and Composer (M5), own indexer and frameworks (M6). ## Progress log | Date | What landed | |---|---| +| 2026-10-16 | M1.9b, M1 done: a settings dialog (`Mod+,`) built from the engine's settings, with search, a control per type, reset to default and inline errors; changes apply at once and follow edits from agents live; the theme picker switches at once and the editor font size applies to the editor. | | 2026-10-16 | M1.8: a command palette (`Mod+Shift+P`) finds every command by fuzzy match, recent ones first, with shortcuts shown and unavailable ones dimmed; one global keymap serves engine and UI commands (`Mod+1` toggles the project tree); agents can trigger UI commands over the control channel. | | 2026-10-16 | M1.12: errors and notices reach the user as toasts instead of stderr: a corrupt settings file or recovery entry, a folder that cannot be opened (also with unsaved changes when switching projects), stopped file watching and failed commands without their own UI. Info toasts go away after 5 s, warnings and errors stay. | | 2026-10-16 | M1.7: unsaved text survives a crash. Dirty buffers are journaled about a second after the last edit; the next open offers them in a restore dialog (restore all, selected, or discard), with line endings and BOM kept. | @@ -91,6 +91,7 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a | Date | Change | Summary | |---|---|---| +| 2026-10-16 | minor | M1.9b: M1 done, stage line, Settings row 7% (est.), progress log | | 2026-10-16 | minor | M1.8: progress log, agent automation note (scores unchanged) | | 2026-10-16 | minor | M1.12: progress log (headline unchanged) | | 2026-10-16 | minor | M1.7: Stability 8%, Editor core 9%, feature depth ~1.6% (with Settings 4% from M1.10) | diff --git a/docs/architecture.md b/docs/architecture.md index 80d8ba9..aa81b67 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 and the app icon documented · **Last updated:** 2026-10-16 +> **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 and the app icon documented · **Last updated:** 2026-10-16 ## Overview @@ -140,7 +140,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat - First frame: the desktop reads `appearance.theme` before creating the window and passes `theme::init_script(setting)`, which installs ` diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json index 1790ec1..019dcbe 100644 --- a/ui/src/i18n/en.json +++ b/ui/src/i18n/en.json @@ -56,6 +56,27 @@ "recovery.dialog.restoreSelected": "Restore Selected", "recovery.dialog.savedAt": "Saved {time}", "recovery.dialog.title": "Unsaved changes found", + "settings.appearance.theme.description": "Colours of the whole window. System follows the light or dark preference of your operating system.", + "settings.appearance.theme.label": "Theme", + "settings.appearance.theme.value.lutraDark": "Lutra Dark", + "settings.appearance.theme.value.lutraLight": "Lutra Light", + "settings.appearance.theme.value.system": "Same as system", + "settings.dialog.loadFailed": "Settings could not be loaded: {message}", + "settings.dialog.noMatches": "No settings match your search", + "settings.dialog.reset": "Reset to default", + "settings.dialog.resetLabel": "Reset {name} to default", + "settings.dialog.search": "Search settings", + "settings.dialog.sections": "Settings sections", + "settings.dialog.title": "Settings", + "settings.editor.fontSize.description": "Size of the text in the editor, in pixels.", + "settings.editor.fontSize.label": "Editor font size", + "settings.error.int": "Enter a whole number", + "settings.error.intRange": "Enter a whole number from {min} to {max}", + "settings.section.appearance": "Appearance", + "settings.section.editor": "Editor", + "settings.ui.language.description": "Language of the interface. More languages follow.", + "settings.ui.language.label": "Language", + "settings.ui.language.value.en": "English", "theme.lutraDark": "Lutra Dark", "theme.lutraLight": "Lutra Light" } diff --git a/ui/src/ipc.ts b/ui/src/ipc.ts index 25541ec..4ba3663 100644 --- a/ui/src/ipc.ts +++ b/ui/src/ipc.ts @@ -28,6 +28,11 @@ export type EngineEventPayload = | { kind: "fileChangedOnDisk"; path: string; id: number; removed: boolean } | { kind: "watchFailed"; message: string } | { kind: "themeChanged"; id: string; dark: boolean; tokens: Record } + | { + kind: "settingsChanged"; + /** Keys whose effective value changed; unchecked, it comes from the engine. */ + keys: unknown; + } | { kind: "recoveryAvailable"; entries: { path: string; savedAt: number; diskChanged: boolean }[]; diff --git a/ui/src/stores/settings.ts b/ui/src/stores/settings.ts new file mode 100644 index 0000000..c0fa953 --- /dev/null +++ b/ui/src/stores/settings.ts @@ -0,0 +1,425 @@ +/** + * Settings as the engine defines them (`settings.list`) with their + * effective values (`settings.get`), changed through `settings.set` and + * `settings.reset`. + * + * - **Live:** `settingsChanged` (from the dialog, the control channel or + * an agent) reloads the changed values, so every view shows the current + * ones. + * - **Errors:** a refused change keeps the error per key until the value + * changes or another change succeeds; the dialog shows it inline. + * - **Effects:** `editor.fontSize` drives `--lt-font-size-editor` (above + * the theme's value, see `setTokenOverride`). `appearance.theme` needs + * nothing here: the engine answers with `themeChanged`. + * - **Text:** labels, descriptions, section names and enum value names are + * catalog keys (`settings..label`, `settings..description`, + * `settings.section.`, `settings..value.`); the engine + * sends no English for settings. A key the catalog lacks shows as is. + */ +import { defineStore } from "pinia"; +import { reactive, ref } from "vue"; +import { hasMessage, t } from "../i18n"; +import { onEngineEvent, run, type EngineEventPayload } from "../ipc"; +import { setTokenOverride } from "../theme"; + +/** A setting value: settings are scalars. Values from the engine are unchecked. */ +export type SettingValue = string | number | boolean | null; + +/** Types of settings the dialog has a control for. */ +export type SettingType = "enum" | "int" | "bool"; + +/** A setting as `settings.list` describes it. */ +export interface SettingDef { + /** Dotted key, e.g. `editor.fontSize`. */ + key: string; + /** Type, which decides the control. */ + type: SettingType; + /** Default value. */ + default: SettingValue; + /** Accepted values of an enum; empty otherwise. */ + enumValues: string[]; + /** Smallest value of an int, or null. */ + min: number | null; + /** Largest value of an int, or null. */ + max: number | null; + /** Catalog key of the label. */ + labelKey: string; + /** Catalog key of the description. */ + descriptionKey: string; + /** Section id; shown with `settings.section.`. */ + section: string; +} + +/** A section of the dialog with its settings, in engine order. */ +export interface SettingSection { + /** Section id. */ + id: string; + /** Catalog text of `settings.section.`, or the id. */ + label: string; + /** Its settings. */ + settings: SettingDef[]; +} + +/** Key of the editor font size setting. */ +export const FONT_SIZE_KEY = "editor.fontSize"; + +/** Theme token the editor font size drives. */ +export const FONT_SIZE_TOKEN = "--lt-font-size-editor"; + +/** Most settings read from `settings.list`; the rest are dropped. */ +export const MAX_SETTINGS = 1000; + +/** Most characters of a setting value shown in an error or a draft. */ +const MAX_TEXT = 256; + +/** + * A scalar from untrusted data; anything else counts as null. + * + * @param value - the data. + */ +function toScalar(value: unknown): SettingValue { + return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : null; +} + +/** + * Reads one `settings.list` entry from untrusted data. + * + * @param raw - the entry. + * @returns the setting, or null if it is malformed or of an unknown type. + */ +function toSettingDef(raw: unknown): SettingDef | null { + if (typeof raw !== "object" || raw === null) { + return null; + } + const entry = raw as Record; + const { key, type, labelKey, descriptionKey, section, enumValues, min, max } = entry; + if ( + typeof key !== "string" || + typeof labelKey !== "string" || + typeof descriptionKey !== "string" || + typeof section !== "string" || + (type !== "enum" && type !== "int" && type !== "bool") + ) { + return null; + } + const values = Array.isArray(enumValues) + ? (enumValues as unknown[]).filter((v): v is string => typeof v === "string") + : []; + if (type === "enum" && values.length === 0) { + return null; + } + return { + key, + type, + default: toScalar(entry.default), + enumValues: values, + min: typeof min === "number" && Number.isFinite(min) ? min : null, + max: typeof max === "number" && Number.isFinite(max) ? max : null, + labelKey, + descriptionKey, + section, + }; +} + +/** + * Reads the `settings.list` result, keeping well-formed entries. + * + * @param raw - the result. + * @returns the settings, or null if the result is not a list. + */ +export function toSettingDefs(raw: unknown): SettingDef[] | null { + if (!Array.isArray(raw)) { + return null; + } + return (raw as unknown[]) + .slice(0, MAX_SETTINGS) + .map(toSettingDef) + .filter((def): def is SettingDef => def !== null); +} + +/** + * Catalog text of a key, or the fallback when the catalog lacks it. + * + * @param key - the catalog key. + * @param fallback - what to show instead. + */ +function textOr(key: string, fallback: string): string { + return hasMessage(key) ? t(key) : fallback; +} + +/** + * The label of a setting. + * + * @param def - the setting. + */ +export function labelOf(def: SettingDef): string { + return textOr(def.labelKey, def.key); +} + +/** + * The description of a setting; empty when the catalog lacks it. + * + * @param def - the setting. + */ +export function descriptionOf(def: SettingDef): string { + return textOr(def.descriptionKey, ""); +} + +/** + * The name of a section. + * + * @param id - the section id. + */ +export function sectionLabel(id: string): string { + return textOr(`settings.section.${id}`, id); +} + +/** + * The name of an enum value: `settings..value.` with the value + * in camel case (`lutra-dark` → `lutraDark`), or the value itself. + * + * @param def - the setting. + * @param value - one of its values. + */ +export function valueLabel(def: SettingDef, value: string): string { + const name = value.replace(/[-_.\s]+([A-Za-z0-9])/g, (_m, c: string) => c.toUpperCase()); + return textOr(`settings.${def.key}.value.${name}`, value); +} + +/** + * Whether a setting matches a search: every word of the query occurs in + * its label, description, key or section name (ignoring case). + * + * @param def - the setting. + * @param query - what the user typed. + */ +export function matchesQuery(def: SettingDef, query: string): boolean { + const words = query.toLowerCase().split(/\s+/).filter((w) => w !== ""); + if (words.length === 0) { + return true; + } + const haystack = [labelOf(def), descriptionOf(def), def.key, sectionLabel(def.section)] + .join("\n") + .toLowerCase(); + return words.every((word) => haystack.includes(word)); +} + +/** + * Groups settings into sections, in the order they first appear. + * + * @param defs - the settings. + */ +export function groupSections(defs: readonly SettingDef[]): SettingSection[] { + const sections: SettingSection[] = []; + for (const def of defs) { + let section = sections.find((s) => s.id === def.section); + if (!section) { + section = { id: def.section, label: sectionLabel(def.section), settings: [] }; + sections.push(section); + } + section.settings.push(def); + } + return sections; +} + +/** + * Whether two setting values are equal. + * + * @param a - one value. + * @param b - the other. + */ +function sameValue(a: SettingValue | undefined, b: SettingValue | undefined): boolean { + return a === b; +} + +/** + * Shortens a text for display. + * + * @param text - the text. + */ +function clip(text: string): string { + return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text; +} + +/** Store of the settings, their values and refused changes. */ +export const useSettingsStore = defineStore("settings", () => { + /** Settings as the engine lists them; empty until loaded. */ + const defs = ref([]); + /** Effective values by key. */ + const values = reactive>({}); + /** Error of the last refused change, by key. */ + const errors = reactive>({}); + /** Why loading failed, or null. */ + const loadError = ref(null); + /** Ends the engine event subscription; set while started. */ + let unsubscribe: (() => void) | null = null; + + /** + * Applies what a value change means outside the dialog: the editor font + * size token. + * + * @param key - the changed key. + */ + function applyEffect(key: string): void { + if (key !== FONT_SIZE_KEY) { + return; + } + const size = values[key]; + setTokenOverride( + FONT_SIZE_TOKEN, + typeof size === "number" && Number.isInteger(size) && size > 0 ? `${String(size)}px` : null, + ); + } + + /** + * Stores values read from the engine and applies their effects. + * + * @param raw - `{values: {key: value}}` from `settings.get`; unchecked. + */ + function storeValues(raw: unknown): void { + if (typeof raw !== "object" || raw === null) { + return; + } + const read = (raw as { values?: unknown }).values; + if (typeof read !== "object" || read === null) { + return; + } + for (const [key, value] of Object.entries(read as Record)) { + values[key] = toScalar(value); + applyEffect(key); + } + } + + /** + * Reads values from the engine. + * + * @param keys - keys to read; every setting when absent. + * @returns whether it worked. + */ + async function fetchValues(keys?: string[]): Promise { + const result = await run("settings.get", keys ? { keys } : {}); + if (!result.ok) { + loadError.value = result.error.message; + return false; + } + storeValues(result.value); + return true; + } + + /** Loads the settings and their values; a failure is kept in `loadError`. */ + async function load(): Promise { + const listed = await run("settings.list"); + const list = listed.ok ? toSettingDefs(listed.value) : null; + if (!list) { + loadError.value = listed.ok ? t("common.error.unexpectedResult", { command: "settings.list" }) : listed.error.message; + return; + } + defs.value = list; + if (await fetchValues()) { + loadError.value = null; + } + } + + /** + * Whether a setting has its default value. + * + * @param def - the setting. + */ + function isDefault(def: SettingDef): boolean { + return sameValue(values[def.key], def.default); + } + + /** + * Stores the outcome of `settings.set` or `settings.reset`. + * + * @param key - the setting. + * @param result - the command's outcome. + * @returns whether the change was accepted. + */ + function settle( + key: string, + result: { ok: true; value: unknown } | { ok: false; error: { message: string } }, + ): boolean { + if (!result.ok) { + errors[key] = clip(result.error.message); + return false; + } + Reflect.deleteProperty(errors, key); + const value = (result.value as { value?: unknown } | null)?.value; + if (value !== undefined) { + values[key] = toScalar(value); + applyEffect(key); + } + return true; + } + + /** + * Changes a setting through `settings.set`. A refused value keeps the + * engine's message as the key's error. + * + * @param key - the setting. + * @param value - the new value. + * @returns whether the engine accepted it. + */ + async function set(key: string, value: SettingValue): Promise { + return settle(key, await run("settings.set", { key, value })); + } + + /** + * Resets a setting to its default through `settings.reset`. + * + * @param key - the setting. + * @returns whether it worked. + */ + async function reset(key: string): Promise { + return settle(key, await run("settings.reset", { key })); + } + + /** + * Records an error found before asking the engine (a number field with + * text that is no whole number). + * + * @param key - the setting. + * @param message - the error text. + */ + function setError(key: string, message: string): void { + errors[key] = message; + } + + /** + * Reloads the values a `settingsChanged` event names and drops their + * errors: the value changed after them. + * + * @param event - the engine event. + */ + function onEvent(event: EngineEventPayload): void { + if (event.kind !== "settingsChanged" || !Array.isArray(event.keys)) { + return; + } + const keys = (event.keys as unknown[]).filter((k): k is string => typeof k === "string"); + if (keys.length === 0) { + return; + } + for (const key of keys) { + Reflect.deleteProperty(errors, key); + } + void fetchValues(keys); + } + + /** Starts following `settingsChanged` and loads the settings. Starting twice is a no-op. */ + async function start(): Promise { + if (unsubscribe) { + return; + } + unsubscribe = onEngineEvent(onEvent); + await load(); + } + + /** Stops following `settingsChanged`. */ + function stop(): void { + unsubscribe?.(); + unsubscribe = null; + } + + return { defs, values, errors, loadError, load, isDefault, set, reset, setError, start, stop }; +}); diff --git a/ui/src/theme.ts b/ui/src/theme.ts index c10fc3e..8286f8c 100644 --- a/ui/src/theme.ts +++ b/ui/src/theme.ts @@ -47,9 +47,45 @@ export function toResolvedTheme(value: unknown): ResolvedTheme | null { return { id, dark, tokens: clean }; } +/** Token values that settings put above the theme's (`--lt-font-size-editor`). */ +const overrides = new Map(); + +/** The last theme's value of every token, to restore when an override ends. */ +const themeTokens = new Map(); + +/** + * Puts a value above a theme token, now and for every theme applied later, + * so a setting such as `editor.fontSize` survives a theme switch. `null` + * ends the override and restores the theme's value, or the injected + * style's when no theme was applied yet. + * + * @param name - the token, `--lt-…`. + * @param value - the CSS value, or null. + * @param root - the element to theme; the document element by default. + */ +export function setTokenOverride( + name: string, + value: string | null, + root: HTMLElement = document.documentElement, +): void { + if (value === null) { + overrides.delete(name); + const base = themeTokens.get(name); + if (base === undefined) { + root.style.removeProperty(name); + } else { + root.style.setProperty(name, base); + } + return; + } + overrides.set(name, value); + root.style.setProperty(name, value); +} + /** * Applies a theme: writes its tokens onto the root element's inline style - * (which wins over the injected `