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,32 +1,49 @@
/**
* Thin adapter between the project UI and the engine event stream.
* Thin adapter between the project UI and the engine.
*
* The desktop bridge (M1.4) will add a typed `onEngineEvent(handler) =>
* unsubscribe` to `ui/src/ipc.ts`, fed by the Tauri event `engine://event`.
* Until it lands, this module provides the same signature backed by a local
* dispatcher so the store and its tests can be written against it. Wiring the
* real stream is a one-line change: replace the local {@link onEngineEvent}
* with `export { onEngineEvent } from "../../ipc";`.
* Translates the engine's contract into the types the project store and tree
* use: engine events (`ui/src/ipc.ts` › `onEngineEvent`, tagged by `kind`)
* become {@link EngineEvent}s, and `project.children` results become
* {@link TreeListing}s through {@link toTreeEntries}. Keeping the
* translation here lets the store stay independent of the wire format.
*
* The event and payload shapes below follow the planned engine `Event` enum
* (M1.3) and are the frontend's assumption until that lands.
* Subscriptions go through a local dispatcher: the first handler opens one
* subscription to the real event stream, the last one closes it. Tests feed
* the dispatcher with {@link emitEngineEvent} using engine payloads, so the
* translation is tested too.
*/
import { onEngineEvent as onIpcEngineEvent, type EngineEventPayload } from "../../ipc";
/** Kind of a project tree entry as reported by `project.children`. */
/** Kind of a project tree entry. Engine kinds `file` and `other` are both leaves. */
export type TreeEntryKind = "dir" | "file";
/** One entry of a directory listing, as returned by `project.children`. */
/** Lutra's role for an entry: third-party `library` code or `excluded` from the project model. */
export type EntryRole = "normal" | "library" | "excluded";
/** One entry of a directory listing. */
export interface TreeEntry {
/** File or directory name, without any path. */
name: string;
/** Project-relative path with `/` separators; the root is `""`. */
path: string;
/** Whether the entry is a directory or a file. */
/** Whether the entry is a directory or a leaf. */
kind: TreeEntryKind;
/** Matched by an ignore rule (`.gitignore`, `.ignore`, global excludes). */
ignored: boolean;
/** Excluded from the project model (for example `node_modules/`). */
/** Lutra's role for the entry; `normal` when the engine did not send one. */
role?: EntryRole;
/** Excluded from the project model (for example `node_modules/`); same as `role === "excluded"`. */
excluded?: boolean;
/** Neither a file nor a directory (a broken link, a socket). */
special?: boolean;
}
/** A translated `project.children` result. */
export interface TreeListing {
/** The entries, in engine order. */
entries: TreeEntry[];
/** The directory had more entries than the engine lists. */
truncated: boolean;
}
/** The project root, as carried by the `ProjectOpened` event. */
@ -38,42 +55,134 @@ export interface ProjectRoot {
}
/**
* Engine events the project UI reacts to. The engine sends more kinds
* (buffer events); consumers ignore any `type` they do not handle.
* Engine events the project UI reacts to. Other engine events are not
* translated and never reach project handlers.
*/
export type EngineEvent =
| { type: "ProjectOpened"; root: ProjectRoot }
| { type: "ProjectClosed" }
| { type: "TreeChanged"; dir: string };
/** Callback receiving engine events. */
/** Callback receiving project events. */
export type EngineEventHandler = (event: EngineEvent) => void;
/**
* Translates an engine event into a project event.
*
* @param payload - the engine event.
* @returns the project event, or null for kinds the project UI ignores.
*/
export function toProjectEvent(payload: EngineEventPayload): EngineEvent | null {
switch (payload.kind) {
case "projectOpened":
return { type: "ProjectOpened", root: { path: payload.root, name: payload.name } };
case "projectClosed":
return { type: "ProjectClosed" };
case "treeChanged":
return { type: "TreeChanged", dir: payload.dir };
default:
return null;
}
}
/** Reads a string field of an unknown object. */
function stringField(value: Record<string, unknown>, key: string): string | null {
const field = value[key];
return typeof field === "string" ? field : null;
}
/**
* Translates one engine entry.
*
* @param raw - an entry of the engine's `entries` array.
* @returns the tree entry, or null if the entry is malformed.
*/
function toTreeEntry(raw: unknown): TreeEntry | null {
if (typeof raw !== "object" || raw === null) {
return null;
}
const value = raw as Record<string, unknown>;
const name = stringField(value, "name");
const path = stringField(value, "path");
const kind = stringField(value, "kind");
if (name === null || path === null || kind === null) {
return null;
}
const roleField = stringField(value, "role");
const role: EntryRole = roleField === "library" || roleField === "excluded" ? roleField : "normal";
return {
name,
path,
kind: kind === "directory" ? "dir" : "file",
ignored: value.ignored === true,
role,
excluded: role === "excluded",
special: kind === "other",
};
}
/**
* Translates a `project.children` result
* (`{ dir, entries: [{ name, path, kind, ignored, role }], truncated }`).
* Malformed entries are skipped.
*
* @param value - the command result.
* @returns the listing, or null if the result has no `entries` array.
*/
export function toTreeEntries(value: unknown): TreeListing | null {
if (typeof value !== "object" || value === null) {
return null;
}
const result = value as Record<string, unknown>;
if (!Array.isArray(result.entries)) {
return null;
}
const entries: TreeEntry[] = [];
for (const raw of result.entries as unknown[]) {
const entry = toTreeEntry(raw);
if (entry) {
entries.push(entry);
}
}
return { entries, truncated: result.truncated === true };
}
/** Handlers subscribed through the local dispatcher. */
const handlers = new Set<EngineEventHandler>();
/** Ends the subscription to the real event stream, null while closed. */
let stopIpc: (() => void) | null = null;
/**
* Subscribes to engine events.
* Delivers an engine event to every project handler, translated. Used by
* the real event stream and by tests.
*
* @param payload - the engine event.
*/
export function emitEngineEvent(payload: EngineEventPayload): void {
const event = toProjectEvent(payload);
if (!event) {
return;
}
for (const handler of [...handlers]) {
handler(event);
}
}
/**
* Subscribes to project events.
*
* @param handler - called for every event, in order of arrival.
* @returns a function that removes the subscription.
*/
export function onEngineEvent(handler: EngineEventHandler): () => void {
handlers.add(handler);
stopIpc ??= onIpcEngineEvent(emitEngineEvent);
return () => {
handlers.delete(handler);
if (handlers.size === 0) {
stopIpc?.();
stopIpc = null;
}
};
}
/**
* Delivers an event to every subscriber of the local dispatcher. Used by
* tests and as the mock engine until the desktop bridge exists; removed when
* {@link onEngineEvent} is wired to `ui/src/ipc.ts`.
*
* @param event - the event to deliver.
*/
export function emitEngineEvent(event: EngineEvent): void {
for (const handler of [...handlers]) {
handler(event);
}
}

View file

@ -3,9 +3,71 @@
*
* 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.
* every caller has to handle them. State changes arrive as engine events
* through {@link onEngineEvent}.
*/
import { invoke } from "@tauri-apps/api/core";
import { listen, type UnlistenFn } from "@tauri-apps/api/event";
/** Name of the Tauri event that carries engine events. */
export const ENGINE_EVENT = "engine://event";
/**
* An engine event as the desktop shell emits it: the engine's `Event`,
* tagged by `kind`. Paths are project-relative with `/`; the root is `""`.
*/
export type EngineEventPayload =
| { kind: "projectOpened"; root: string; name: string }
| { kind: "projectClosed" }
| { kind: "treeChanged"; dir: string }
| { kind: "bufferOpened"; id: number; path: string }
| { kind: "bufferChanged"; id: number; version: number }
| { kind: "dirtyChanged"; id: number; dirty: boolean }
| { kind: "bufferClosed"; id: number }
| { kind: "fileChangedOnDisk"; path: string; id: number; removed: boolean }
| { kind: "watchFailed"; message: string };
/** Callback receiving engine events. */
export type EngineEventHandler = (event: EngineEventPayload) => void;
/** Whether the shell was told that the frontend listens (`engine_ready`). */
let announced = false;
/**
* Subscribes to engine events. The first successful subscription tells the
* shell that the frontend listens, so it replays the current project state
* the page may have missed while loading. Outside the Tauri shell (tests,
* a plain browser) subscribing fails quietly and no events arrive.
*
* @param handler - called for every event, in order of arrival.
* @returns a function that ends the subscription.
*/
export function onEngineEvent(handler: EngineEventHandler): () => void {
let unlisten: UnlistenFn | null = null;
let cancelled = false;
listen<EngineEventPayload>(ENGINE_EVENT, (event) => {
handler(event.payload);
})
.then((fn) => {
if (cancelled) {
fn();
return;
}
unlisten = fn;
if (!announced) {
announced = true;
invoke("engine_ready").catch(() => {
announced = false;
});
}
})
.catch(() => undefined);
return () => {
cancelled = true;
unlisten?.();
unlisten = null;
};
}
/** A JSON value as exchanged with the engine. */
export type JsonValue =

View file

@ -12,6 +12,7 @@ import { computed, ref } from "vue";
import { run, type EngineError } from "../ipc";
import {
onEngineEvent,
toTreeEntries,
type EngineEvent,
type ProjectRoot,
type TreeEntry,
@ -19,7 +20,7 @@ import {
/** Engine command ids used by the project tool window. */
export const PROJECT_COMMANDS = {
/** Lists one directory: params `{ dir }`, result `TreeEntry[]`. */
/** Lists one directory: params `{ dir }`, result `{ dir, entries, truncated }` (see `toTreeEntries`). */
children: "project.children",
/** Shows the folder picker and opens the chosen folder. */
openDialog: "project.openDialog",
@ -35,6 +36,8 @@ export interface DirState {
loading: boolean;
/** Error of the last `project.children` call, null if it succeeded. */
error: EngineError | null;
/** The engine listed only part of the directory. */
truncated: boolean;
}
/** A visible line of the flattened tree. */
@ -136,17 +139,26 @@ export const useProjectStore = defineStore("project", () => {
async function loadChildren(dir: string): Promise<void> {
const request = ++nextRequest;
requests.set(dir, request);
dirs.value[dir] = { entries: cachedEntries(dir), loading: true, error: null };
const result = await run<TreeEntry[]>(PROJECT_COMMANDS.children, { dir });
const truncated = dirs.value[dir]?.truncated ?? false;
dirs.value[dir] = { entries: cachedEntries(dir), loading: true, error: null, truncated };
const result = await run<unknown>(PROJECT_COMMANDS.children, { dir });
if (requests.get(dir) !== request) {
return;
}
if (result.ok) {
const entries = result.value;
dirs.value[dir] = { entries, loading: false, error: null };
prune(dir, entries);
const listing = result.ok ? toTreeEntries(result.value) : null;
if (listing) {
dirs.value[dir] = {
entries: listing.entries,
loading: false,
error: null,
truncated: listing.truncated,
};
prune(dir, listing.entries);
} else {
dirs.value[dir] = { entries: cachedEntries(dir), loading: false, error: result.error };
const error = result.ok
? { code: "ipc", message: `unexpected result of ${PROJECT_COMMANDS.children}` }
: result.error;
dirs.value[dir] = { entries: cachedEntries(dir), loading: false, error, truncated };
}
}