diff --git a/docs/development.md b/docs/development.md index 95665c9..bc9306d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,11 +1,11 @@ # Development -> **Status:** draft · **Last updated:** 2026-10-13 +> **Status:** draft · **Last updated:** 2026-10-14 ## Prerequisites - Rust stable (via rustup), edition 2024 -- Node.js 20 or newer and pnpm +- Node.js 22.12 or newer (Vite 8 needs it) and pnpm 10 - 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 @@ -29,4 +29,5 @@ No inline comments. Doc comment blocks above modules, functions, types and field | Date | Change | Summary | |---|---|---| +| 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain | | 2026-10-13 | major | Initial draft | diff --git a/ui/eslint.config.js b/ui/eslint.config.js new file mode 100644 index 0000000..e2db329 --- /dev/null +++ b/ui/eslint.config.js @@ -0,0 +1,43 @@ +/** + * ESLint flat configuration of the Lutra frontend. + * + * Type-aware TypeScript rules apply to `.ts` and `.vue` files. Floating and + * misused promises are errors so that no rejection goes unhandled, `any` + * is an error, and inline comments are banned in favour of TSDoc blocks. + */ +import js from "@eslint/js"; +import { defineConfig } from "eslint/config"; +import pluginVue from "eslint-plugin-vue"; +import globals from "globals"; +import tseslint from "typescript-eslint"; +import vueParser from "vue-eslint-parser"; + +export default defineConfig( + { ignores: ["dist/**", "node_modules/**", "coverage/**"] }, + js.configs.recommended, + tseslint.configs.strictTypeChecked, + pluginVue.configs["flat/recommended"], + { + languageOptions: { + parser: vueParser, + parserOptions: { + parser: tseslint.parser, + projectService: true, + tsconfigRootDir: import.meta.dirname, + extraFileExtensions: [".vue"], + }, + globals: { ...globals.browser }, + }, + rules: { + "@typescript-eslint/no-floating-promises": "error", + "@typescript-eslint/no-misused-promises": "error", + "@typescript-eslint/no-explicit-any": "error", + "no-inline-comments": "error", + }, + }, + { + files: ["**/*.js"], + extends: [tseslint.configs.disableTypeChecked], + languageOptions: { globals: { ...globals.node } }, + }, +); diff --git a/ui/index.html b/ui/index.html new file mode 100644 index 0000000..f28a346 --- /dev/null +++ b/ui/index.html @@ -0,0 +1,12 @@ + + + + + + Lutra + + +
+ + + diff --git a/ui/package.json b/ui/package.json index 20a2372..2e4c50d 100644 --- a/ui/package.json +++ b/ui/package.json @@ -4,6 +4,10 @@ "version": "0.0.0", "license": "MIT OR Apache-2.0", "type": "module", + "engines": { + "node": ">=22.12" + }, + "packageManager": "pnpm@10.34.7", "scripts": { "dev": "vite", "build": "vue-tsc --noEmit && vite build", diff --git a/ui/src/App.vue b/ui/src/App.vue new file mode 100644 index 0000000..ffda0ad --- /dev/null +++ b/ui/src/App.vue @@ -0,0 +1,49 @@ + + + + + diff --git a/ui/src/components/StatusBar.vue b/ui/src/components/StatusBar.vue new file mode 100644 index 0000000..0c837bb --- /dev/null +++ b/ui/src/components/StatusBar.vue @@ -0,0 +1,45 @@ + + + + + diff --git a/ui/src/env.d.ts b/ui/src/env.d.ts new file mode 100644 index 0000000..c980c07 --- /dev/null +++ b/ui/src/env.d.ts @@ -0,0 +1,10 @@ +/** + * Module declaration for single-file components, so that tools without Vue + * support (the ESLint type checker) see `.vue` imports as components. + * `vue-tsc` resolves the real component types. + */ +declare module "*.vue" { + import type { DefineComponent } from "vue"; + const component: DefineComponent; + export default component; +} diff --git a/ui/src/ipc.ts b/ui/src/ipc.ts new file mode 100644 index 0000000..cefb2a9 --- /dev/null +++ b/ui/src/ipc.ts @@ -0,0 +1,95 @@ +/** + * Bridge from the frontend to the engine. + * + * Every user-visible action runs as an engine command through {@link run}. + * Calls never reject: failures come back as `{ ok: false, error }` so that + * every caller has to handle them. + */ +import { invoke } from "@tauri-apps/api/core"; + +/** A JSON value as exchanged with the engine. */ +export type JsonValue = + | null + | boolean + | number + | string + | JsonValue[] + | { [key: string]: JsonValue }; + +/** An error reported by the engine, with a stable machine-readable code. */ +export interface EngineError { + /** Stable code such as `unknown_command`, `invalid_params` or `internal`. */ + code: string; + /** Message for the user. */ + message: string; +} + +/** Outcome of an engine call. */ +export type RunResult = { ok: true; value: T } | { ok: false; error: EngineError }; + +/** Static description of a command, as listed by the engine. */ +export interface CommandInfo { + /** Command id, e.g. `app.about`. */ + id: string; + /** Label shown in menus and the command palette. */ + label: string; + /** Menu path such as `Help/About Lutra`, or null if not in a menu. */ + menuPath: string | null; + /** Default shortcut in Lutra notation (`Mod+Q`), or null. */ + defaultShortcut: string | null; + /** Documentation of the params object. */ + params: string; + /** Whether the command can run in the current state. */ + enabled: boolean; +} + +/** + * Turns whatever a failed `invoke` rejected with into an {@link EngineError}. + * + * @param reason - the rejection value; the shell sends `{ code, message }`. + * @returns the engine error, or an `ipc` error for anything else (for example + * when the page runs outside the Tauri shell). + */ +export function toEngineError(reason: unknown): EngineError { + if (typeof reason === "object" && reason !== null && "code" in reason && "message" in reason) { + const { code, message } = reason; + if (typeof code === "string" && typeof message === "string") { + return { code, message }; + } + } + const message = reason instanceof Error ? reason.message : String(reason); + return { code: "ipc", message }; +} + +/** + * Runs an engine command. + * + * @param commandId - the command id, e.g. `app.about`. + * @param params - the command's params object. + * @returns the command's result, or the error it failed with. + */ +export async function run( + commandId: string, + params: JsonValue = {}, +): Promise> { + try { + const value = await invoke("engine_execute", { command: commandId, params }); + return { ok: true, value }; + } catch (reason: unknown) { + return { ok: false, error: toEngineError(reason) }; + } +} + +/** + * Lists every command the engine knows, with its current enabled state. + * + * @returns the commands, or the error the call failed with. + */ +export async function listCommands(): Promise> { + try { + const value = await invoke("engine_list_commands"); + return { ok: true, value }; + } catch (reason: unknown) { + return { ok: false, error: toEngineError(reason) }; + } +} diff --git a/ui/src/main.ts b/ui/src/main.ts new file mode 100644 index 0000000..1d592bc --- /dev/null +++ b/ui/src/main.ts @@ -0,0 +1,10 @@ +/** + * Entry point of the Lutra frontend: creates the Vue app with Pinia and + * mounts it on `#app`. + */ +import { createPinia } from "pinia"; +import { createApp } from "vue"; +import App from "./App.vue"; +import "./styles/base.css"; + +createApp(App).use(createPinia()).mount("#app"); diff --git a/ui/src/stores/app.ts b/ui/src/stores/app.ts new file mode 100644 index 0000000..b957792 --- /dev/null +++ b/ui/src/stores/app.ts @@ -0,0 +1,38 @@ +/** + * Application-wide state: product information from `app.about` and the + * last error the shell reported. + */ +import { defineStore } from "pinia"; +import { ref } from "vue"; +import { run, type EngineError } from "../ipc"; + +/** Result of the `app.about` command. */ +export interface AboutInfo { + /** Product name. */ + name: string; + /** Version of the running build. */ + version: string; + /** Slogan shown in the About window. */ + slogan: string; +} + +/** Store holding product information and the last engine error. */ +export const useAppStore = defineStore("app", () => { + /** Product information, null until loaded. */ + const about = ref(null); + /** Last error from the engine, null if none. */ + const lastError = ref(null); + + /** Loads product information from the engine; on failure records the error. */ + async function loadAbout(): Promise { + const result = await run("app.about"); + if (result.ok) { + about.value = result.value; + lastError.value = null; + } else { + lastError.value = result.error; + } + } + + return { about, lastError, loadAbout }; +}); diff --git a/ui/src/styles/base.css b/ui/src/styles/base.css new file mode 100644 index 0000000..a390fe5 --- /dev/null +++ b/ui/src/styles/base.css @@ -0,0 +1,19 @@ +/** + * Base layout of the Lutra window. Colours and fonts come only from the + * theme tokens (`--lt-*`) that the desktop shell injects before first paint. + */ +html, +body, +#app { + height: 100%; + margin: 0; +} + +body { + background: var(--lt-bg); + color: var(--lt-fg); + font-family: var(--lt-font-ui); + font-size: var(--lt-font-size-ui); + overflow: hidden; + user-select: none; +} diff --git a/ui/tests/App.test.ts b/ui/tests/App.test.ts new file mode 100644 index 0000000..b391795 --- /dev/null +++ b/ui/tests/App.test.ts @@ -0,0 +1,36 @@ +/** + * Tests for the root component: it loads product information on mount and + * shows it, or the error, in the status bar. + */ +import { flushPromises, mount } from "@vue/test-utils"; +import { createPinia, setActivePinia } from "pinia"; +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const invoke = vi.hoisted(() => vi.fn()); +vi.mock("@tauri-apps/api/core", () => ({ invoke })); + +import App from "../src/App.vue"; + +describe("App", () => { + beforeEach(() => { + invoke.mockReset(); + setActivePinia(createPinia()); + }); + + it("shows name and version in the status bar", async () => { + invoke.mockResolvedValue({ name: "Lutra", version: "0.0.0", slogan: "An otterly perfect IDE" }); + const wrapper = mount(App); + await flushPromises(); + expect(wrapper.get("[data-test=status-bar]").text()).toBe("Lutra 0.0.0"); + expect(wrapper.get("[data-test=main]").text()).toBe("An otterly perfect IDE"); + }); + + it("shows the engine error when the call fails", async () => { + invoke.mockRejectedValue({ code: "internal", message: "engine unavailable" }); + const wrapper = mount(App); + await flushPromises(); + const bar = wrapper.get("[data-test=status-bar]"); + expect(bar.text()).toBe("engine unavailable"); + expect(bar.classes()).toContain("status-bar--error"); + }); +}); diff --git a/ui/tests/ipc.test.ts b/ui/tests/ipc.test.ts new file mode 100644 index 0000000..c02054d --- /dev/null +++ b/ui/tests/ipc.test.ts @@ -0,0 +1,55 @@ +/** + * Tests for the engine bridge: results and every kind of rejection map to + * a `RunResult` instead of a rejected promise. + */ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const invoke = vi.hoisted(() => vi.fn()); +vi.mock("@tauri-apps/api/core", () => ({ invoke })); + +import { listCommands, run, toEngineError } from "../src/ipc"; + +describe("run", () => { + beforeEach(() => { + invoke.mockReset(); + }); + + it("passes command and params to the shell", async () => { + invoke.mockResolvedValue({ name: "Lutra" }); + const result = await run("app.about", { verbose: true }); + expect(invoke).toHaveBeenCalledWith("engine_execute", { + command: "app.about", + params: { verbose: true }, + }); + expect(result).toEqual({ ok: true, value: { name: "Lutra" } }); + }); + + it("returns engine errors instead of rejecting", async () => { + invoke.mockRejectedValue({ code: "unknown_command", message: "no such command: x" }); + const result = await run("x"); + expect(result).toEqual({ + ok: false, + error: { code: "unknown_command", message: "no such command: x" }, + }); + }); + + it("wraps unexpected rejections", async () => { + invoke.mockRejectedValue(new Error("window.__TAURI_INTERNALS__ is undefined")); + const result = await run("app.about"); + expect(result.ok).toBe(false); + expect(result.ok ? null : result.error.code).toBe("ipc"); + }); + + it("lists commands", async () => { + invoke.mockResolvedValue([]); + expect(await listCommands()).toEqual({ ok: true, value: [] }); + expect(invoke).toHaveBeenCalledWith("engine_list_commands"); + }); +}); + +describe("toEngineError", () => { + it("handles strings and malformed objects", () => { + expect(toEngineError("boom")).toEqual({ code: "ipc", message: "boom" }); + expect(toEngineError({ code: 1, message: "x" }).code).toBe("ipc"); + }); +}); diff --git a/ui/tsconfig.json b/ui/tsconfig.json new file mode 100644 index 0000000..5a66e76 --- /dev/null +++ b/ui/tsconfig.json @@ -0,0 +1,22 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "Bundler", + "lib": ["ES2022", "DOM", "DOM.Iterable"], + "types": ["node", "vite/client"], + "strict": true, + "noUncheckedIndexedAccess": true, + "noImplicitOverride": true, + "exactOptionalPropertyTypes": true, + "noFallthroughCasesInSwitch": true, + "isolatedModules": true, + "verbatimModuleSyntax": true, + "useDefineForClassFields": true, + "resolveJsonModule": true, + "skipLibCheck": true, + "noEmit": true, + "jsx": "preserve" + }, + "include": ["src/**/*.ts", "src/**/*.vue", "tests/**/*.ts", "vite.config.ts"] +} diff --git a/ui/vite.config.ts b/ui/vite.config.ts new file mode 100644 index 0000000..d8a9a62 --- /dev/null +++ b/ui/vite.config.ts @@ -0,0 +1,15 @@ +/** + * Vite and Vitest configuration of the Lutra frontend. + * + * The dev server port is fixed because the Tauri shell loads it as `devUrl`. + */ +import { defineConfig } from "vitest/config"; +import vue from "@vitejs/plugin-vue"; + +export default defineConfig({ + plugins: [vue()], + clearScreen: false, + server: { port: 5173, strictPort: true }, + build: { target: "es2022", outDir: "dist" }, + test: { environment: "jsdom", include: ["tests/**/*.test.ts"] }, +});