@larose/pi-web 0.3.0

package/src/server/directory-browser.ts

@@ -0,0 +1,137 @@
+import { opendir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+
+import { AppError } from "./errors.js";
+
+const MAX_DIRECTORY_RESULTS = 50;
+const MAX_SCANNED_ENTRIES = 2_000;
+
+export interface DirectorySuggestion {
+  name: string;
+  path: string;
+}
+
+export interface DirectorySuggestionListing {
+  input: string;
+  basePath: string;
+  prefix: string;
+  directories: DirectorySuggestion[];
+  truncated: boolean;
+}
+
+interface BrowseTarget {
+  basePath: string;
+  prefix: string;
+}
+
+function unavailableDirectory(error: unknown): AppError {
+  return new AppError("directory_unavailable", "The directory cannot be read by the server", 400, { cause: error });
+}
+
+async function canonicalDirectory(path: string): Promise<string | null> {
+  try {
+    const canonical = await realpath(path);
+    return (await stat(canonical)).isDirectory() ? canonical : null;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return null;
+    }
+
+    throw unavailableDirectory(error);
+  }
+}
+
+async function browseTarget(input: string): Promise<BrowseTarget> {
+  let candidate = resolve(input);
+  let prefix = "";
+
+  while (true) {
+    const canonical = await canonicalDirectory(candidate);
+    if (canonical) {
+      return { basePath: canonical, prefix };
+    }
+
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      throw new AppError("directory_unavailable", "No readable directory exists for this path", 400);
+    }
+
+    prefix = basename(candidate);
+    candidate = parent;
+  }
+}
+
+function compareSuggestions(left: DirectorySuggestion, right: DirectorySuggestion): number {
+  const folded = left.name.toLocaleLowerCase().localeCompare(right.name.toLocaleLowerCase());
+  return folded || left.name.localeCompare(right.name) || left.path.localeCompare(right.path);
+}
+
+export class DirectoryBrowser {
+  async suggest(input: unknown): Promise<DirectorySuggestionListing> {
+    if (typeof input !== "string" || input.trim() === "") {
+      throw new AppError("invalid_directory_path", "An absolute directory path is required");
+    }
+
+    const requested = input.trim();
+    if (!isAbsolute(requested)) {
+      throw new AppError("invalid_directory_path", "The directory path must be absolute");
+    }
+
+    const target = await browseTarget(requested);
+    const foldedPrefix = target.prefix.toLocaleLowerCase();
+    const directories: DirectorySuggestion[] = [];
+    const canonicalPaths = new Set<string>();
+    let scannedEntries = 0;
+    let truncated = false;
+
+    try {
+      const handle = await opendir(target.basePath);
+      for await (const entry of handle) {
+        scannedEntries += 1;
+        if (scannedEntries > MAX_SCANNED_ENTRIES) {
+          truncated = true;
+          break;
+        }
+        if (!entry.name.toLocaleLowerCase().startsWith(foldedPrefix)) {
+          continue;
+        }
+
+        const entryPath = resolve(target.basePath, entry.name);
+        let canonical: string;
+        try {
+          if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+            continue;
+          }
+          canonical = await realpath(entryPath);
+          if (!(await stat(canonical)).isDirectory()) {
+            continue;
+          }
+        } catch {
+          continue;
+        }
+
+        if (!canonicalPaths.has(canonical)) {
+          canonicalPaths.add(canonical);
+          directories.push({ name: entry.name, path: canonical });
+        }
+      }
+    } catch (error) {
+      throw unavailableDirectory(error);
+    }
+
+    directories.sort(compareSuggestions);
+    if (directories.length > MAX_DIRECTORY_RESULTS) {
+      directories.length = MAX_DIRECTORY_RESULTS;
+      truncated = true;
+    }
+
+    return {
+      input: requested,
+      basePath: target.basePath,
+      prefix: target.prefix,
+      directories,
+      truncated,
+    };
+  }
+}

package/src/server/errors.ts

@@ -0,0 +1,11 @@
+export class AppError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(code: string, message: string, status = 400, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "AppError";
+    this.code = code;
+    this.status = status;
+  }
+}

package/src/server/event-buffer.ts

@@ -0,0 +1,59 @@
+export interface BufferedEvent<T> {
+  id: number;
+  data: T;
+}
+
+export interface EventReplay<T> {
+  events: BufferedEvent<T>[];
+  gap: boolean;
+}
+
+export type EventListener<T> = (event: BufferedEvent<T>) => void;
+
+export class EventBuffer<T> {
+  private readonly capacity: number;
+  private readonly events: BufferedEvent<T>[] = [];
+  private readonly listeners = new Set<EventListener<T>>();
+  private nextId = 1;
+
+  constructor(capacity = 512) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new Error("Event capacity must be a positive integer");
+    }
+    this.capacity = capacity;
+  }
+
+  publish(data: T): BufferedEvent<T> {
+    const event = { id: this.nextId++, data };
+    this.events.push(event);
+    if (this.events.length > this.capacity) {
+      this.events.splice(0, this.events.length - this.capacity);
+    }
+
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+    return event;
+  }
+
+  replay(afterId?: number): EventReplay<T> {
+    if (afterId === undefined) {
+      return { events: [], gap: false };
+    }
+
+    const oldestId = this.events[0]?.id ?? this.nextId;
+    return {
+      events: this.events.filter((event) => event.id > afterId),
+      gap: afterId < oldestId - 1 || afterId >= this.nextId,
+    };
+  }
+
+  subscribe(listener: EventListener<T>): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  get latestId(): number {
+    return this.nextId - 1;
+  }
+}

package/src/server/extension-ui.ts

@@ -0,0 +1,359 @@
+import { randomUUID } from "node:crypto";
+
+import { Theme, type ExtensionUIContext, type ExtensionUIDialogOptions } from "@earendil-works/pi-coding-agent";
+
+export type ExtensionUIDialogRequest =
+  | { id: string; method: "select"; title: string; options: string[]; timeout?: number }
+  | { id: string; method: "confirm"; title: string; message: string; timeout?: number }
+  | { id: string; method: "input"; title: string; placeholder?: string; timeout?: number }
+  | { id: string; method: "editor"; title: string; prefill?: string };
+
+type NewExtensionUIDialogRequest =
+  | { method: "select"; title: string; options: string[] }
+  | { method: "confirm"; title: string; message: string }
+  | { method: "input"; title: string; placeholder?: string }
+  | { method: "editor"; title: string; prefill?: string };
+
+export type ExtensionUIRequest =
+  | ExtensionUIDialogRequest
+  | { id: string; method: "notify"; message: string; notifyType?: "info" | "warning" | "error" }
+  | { id: string; method: "setStatus"; statusKey: string; statusText?: string }
+  | {
+      id: string;
+      method: "setWidget";
+      widgetKey: string;
+      widgetLines?: string[];
+      widgetPlacement?: "aboveEditor" | "belowEditor";
+    }
+  | { id: string; method: "setTitle"; title: string }
+  | { id: string; method: "set_editor_text"; text: string };
+
+export type ExtensionUIResponse =
+  | { id: string; value: string }
+  | { id: string; confirmed: boolean }
+  | { id: string; cancelled: true };
+
+export interface ExtensionUIState {
+  pending: ExtensionUIDialogRequest[];
+  statuses: Array<{ key: string; text: string }>;
+  widgets: Array<{
+    key: string;
+    lines: string[];
+    placement: "aboveEditor" | "belowEditor";
+  }>;
+}
+
+export type ExtensionUIEvent =
+  | ({ type: "extension_ui_request" } & ExtensionUIRequest)
+  | { type: "extension_ui_closed"; id: string }
+  | { type: "extension_ui_reset" };
+
+interface PendingDialog<T> {
+  request: ExtensionUIDialogRequest;
+  defaultValue: T;
+  parse(response: ExtensionUIResponse): T;
+  resolve(value: T): void;
+  timeout?: NodeJS.Timeout;
+  signal?: AbortSignal;
+  abort?: () => void;
+}
+
+// The browser supplies its own colors. Extensions still need a complete Theme
+// object for formatting status and widget text, so keep those operations plain.
+class PlainTextTheme extends Theme {
+  constructor() {
+    super(
+      { text: "", muted: "", thinkingXhigh: "", searchMatchText: "" } as ConstructorParameters<typeof Theme>[0],
+      { selectedBg: "" } as ConstructorParameters<typeof Theme>[1],
+      "truecolor",
+    );
+  }
+
+  override fg(...[, text]: Parameters<Theme["fg"]>): string {
+    return text;
+  }
+  override bg(...[, text]: Parameters<Theme["bg"]>): string {
+    return text;
+  }
+  override bold(text: string): string {
+    return text;
+  }
+  override italic(text: string): string {
+    return text;
+  }
+  override underline(text: string): string {
+    return text;
+  }
+  override inverse(text: string): string {
+    return text;
+  }
+  override strikethrough(text: string): string {
+    return text;
+  }
+  override getFgAnsi(): string {
+    return "";
+  }
+  override getBgAnsi(): string {
+    return "";
+  }
+  override getThinkingBorderColor(): (text: string) => string {
+    return (text) => text;
+  }
+  override getBashModeBorderColor(): (text: string) => string {
+    return (text) => text;
+  }
+}
+
+const plainTextTheme = new PlainTextTheme();
+
+export class WebExtensionUI {
+  private readonly pending = new Map<string, PendingDialog<unknown>>();
+  private readonly statuses = new Map<string, string>();
+  private readonly widgets = new Map<string, { lines: string[]; placement: "aboveEditor" | "belowEditor" }>();
+  private publisher: ((event: ExtensionUIEvent) => void) | undefined;
+  private queuedEvents: ExtensionUIEvent[] = [];
+  private available = true;
+
+  readonly context: ExtensionUIContext = {
+    select: (title, options, opts) =>
+      this.request(
+        { method: "select", title, options: [...options] },
+        undefined,
+        (response) => ("value" in response ? response.value : undefined),
+        opts,
+      ),
+    confirm: (title, message, opts) =>
+      this.request(
+        { method: "confirm", title, message },
+        false,
+        (response) => ("confirmed" in response ? response.confirmed : false),
+        opts,
+      ),
+    input: (title, placeholder, opts) =>
+      this.request(
+        { method: "input", title, ...(placeholder === undefined ? {} : { placeholder }) },
+        undefined,
+        (response) => ("value" in response ? response.value : undefined),
+        opts,
+      ),
+    editor: (title, prefill) =>
+      this.request({ method: "editor", title, ...(prefill === undefined ? {} : { prefill }) }, undefined, (response) =>
+        "value" in response ? response.value : undefined,
+      ),
+    notify: (message, type) =>
+      this.emit({
+        type: "extension_ui_request",
+        id: randomUUID(),
+        method: "notify",
+        message,
+        ...(type === undefined ? {} : { notifyType: type }),
+      }),
+    onTerminalInput: () => () => undefined,
+    setStatus: (key, text) => {
+      if (text === undefined) {
+        this.statuses.delete(key);
+      } else {
+        this.statuses.set(key, text);
+      }
+
+      this.emit({
+        type: "extension_ui_request",
+        id: randomUUID(),
+        method: "setStatus",
+        statusKey: key,
+        ...(text === undefined ? {} : { statusText: text }),
+      });
+    },
+    setWorkingMessage: () => undefined,
+    setWorkingVisible: () => undefined,
+    setWorkingIndicator: () => undefined,
+    setHiddenThinkingLabel: () => undefined,
+    setWidget: (key, content, options) => {
+      if (content !== undefined && !Array.isArray(content)) {
+        return;
+      }
+
+      const placement = options?.placement ?? "aboveEditor";
+      if (content === undefined) {
+        this.widgets.delete(key);
+      } else {
+        this.widgets.set(key, { lines: [...content], placement });
+      }
+
+      this.emit({
+        type: "extension_ui_request",
+        id: randomUUID(),
+        method: "setWidget",
+        widgetKey: key,
+        ...(content === undefined ? {} : { widgetLines: [...content] }),
+        ...(options?.placement === undefined ? {} : { widgetPlacement: options.placement }),
+      });
+    },
+    setFooter: () => undefined,
+    setHeader: () => undefined,
+    setTitle: (title) =>
+      this.emit({
+        type: "extension_ui_request",
+        id: randomUUID(),
+        method: "setTitle",
+        title,
+      }),
+    custom: async <T>() => undefined as T,
+    pasteToEditor: (text) =>
+      this.emit({
+        type: "extension_ui_request",
+        id: randomUUID(),
+        method: "set_editor_text",
+        text,
+      }),
+    setEditorText: (text) =>
+      this.emit({
+        type: "extension_ui_request",
+        id: randomUUID(),
+        method: "set_editor_text",
+        text,
+      }),
+    getEditorText: () => "",
+    addAutocompleteProvider: () => undefined,
+    setEditorComponent: () => undefined,
+    getEditorComponent: () => undefined,
+    get theme() {
+      return plainTextTheme;
+    },
+    getAllThemes: () => [],
+    getTheme: () => undefined,
+    setTheme: () => ({ success: false, error: "Theme switching is not supported in Pi Web" }),
+    getToolsExpanded: () => false,
+    setToolsExpanded: () => undefined,
+  };
+
+  setPublisher(publisher: (event: ExtensionUIEvent) => void): () => void {
+    this.publisher = publisher;
+
+    const queued = this.queuedEvents;
+    this.queuedEvents = [];
+    for (const event of queued) {
+      publisher(event);
+    }
+
+    return () => {
+      if (this.publisher === publisher) {
+        this.publisher = undefined;
+      }
+    };
+  }
+
+  snapshot(): ExtensionUIState {
+    return {
+      pending: [...this.pending.values()].map(({ request }) => ({ ...request })),
+      statuses: [...this.statuses].map(([key, text]) => ({ key, text })),
+      widgets: [...this.widgets].map(([key, widget]) => ({
+        key,
+        lines: [...widget.lines],
+        placement: widget.placement,
+      })),
+    };
+  }
+
+  respond(response: ExtensionUIResponse): boolean {
+    const dialog = this.pending.get(response.id);
+    if (!dialog) {
+      return false;
+    }
+
+    this.settle(response.id, dialog.parse(response));
+    return true;
+  }
+
+  cancelPending(): void {
+    for (const [id, dialog] of [...this.pending]) {
+      this.settle(id, dialog.defaultValue);
+    }
+  }
+
+  reset(): void {
+    this.cancelPending();
+    this.statuses.clear();
+    this.widgets.clear();
+    this.emit({ type: "extension_ui_reset" });
+  }
+
+  dispose(): void {
+    if (!this.available) {
+      return;
+    }
+
+    this.reset();
+    this.available = false;
+    this.publisher = undefined;
+    this.queuedEvents = [];
+  }
+
+  private request<T>(
+    request: NewExtensionUIDialogRequest,
+    defaultValue: T,
+    parse: (response: ExtensionUIResponse) => T,
+    options?: ExtensionUIDialogOptions,
+  ): Promise<T> {
+    if (!this.available || options?.signal?.aborted) {
+      return Promise.resolve(defaultValue);
+    }
+
+    const id = randomUUID();
+    const fullRequest = {
+      id,
+      ...request,
+      ...(options?.timeout === undefined ? {} : { timeout: options.timeout }),
+    } as ExtensionUIDialogRequest;
+
+    return new Promise<T>((resolve) => {
+      const pending: PendingDialog<T> = {
+        request: fullRequest,
+        defaultValue,
+        parse,
+        resolve,
+        ...(options?.signal === undefined ? {} : { signal: options.signal }),
+      };
+      if (options?.timeout !== undefined) {
+        pending.timeout = setTimeout(() => this.settle(id, defaultValue), options.timeout);
+        pending.timeout.unref();
+      }
+      if (options?.signal) {
+        pending.abort = () => this.settle(id, defaultValue);
+        options.signal.addEventListener("abort", pending.abort, { once: true });
+      }
+
+      this.pending.set(id, pending as PendingDialog<unknown>);
+      this.emit({ type: "extension_ui_request", ...fullRequest });
+    });
+  }
+
+  private settle<T>(id: string, value: T): void {
+    const dialog = this.pending.get(id) as PendingDialog<T> | undefined;
+    if (!dialog) {
+      return;
+    }
+
+    this.pending.delete(id);
+    if (dialog.timeout) {
+      clearTimeout(dialog.timeout);
+    }
+    if (dialog.signal && dialog.abort) {
+      dialog.signal.removeEventListener("abort", dialog.abort);
+    }
+    dialog.resolve(value);
+    this.emit({ type: "extension_ui_closed", id });
+  }
+
+  private emit(event: ExtensionUIEvent): void {
+    if (!this.available) {
+      return;
+    }
+
+    if (this.publisher) {
+      this.publisher(event);
+    } else {
+      this.queuedEvents.push(event);
+    }
+  }
+}