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);
}
}