@mrdrmccoy/xerj-opencode-plugin 0.0.0-stage → 0.4.1

package/src/tui.tsx

@@ -0,0 +1,362 @@
+// TUI part: a live sidebar block, a details panel, and four commands. Every
+// value comes over RPC from the server part, so the TUI never opens the node,
+// reads the index, or touches the filesystem.
+
+import { Plugin } from "@opencode/plugin/tui";
+import { XerjRpc, type StatusSnapshot } from "./rpc.ts";
+import { panelSections, sidebarLines } from "./ui/format.ts";
+
+const PANEL_NAME = "xerj.stats";
+const FALLBACK_POLL_MS = 30_000;
+const SEARCH_CLIP = 6_000;
+
+interface TuiState {
+  lines: string[];
+  ready: boolean;
+  snapshot: StatusSnapshot | null;
+  reason: string | null;
+}
+
+export default Plugin.define({
+  id: "xerj.tui",
+  setup(context) {
+    // Read the client on every call: the host replaces it after a server
+    // restart, and a captured sub-client then fails without sending anything.
+    const rpc = () => context.client.rpc(XerjRpc);
+    const [state, update] = context.storage.memory<TuiState>("status", {
+      initial: {
+        lines: ["XERJ  ○ starting"],
+        ready: false,
+        snapshot: null,
+        reason: null,
+      },
+    });
+
+    // The RPC lookup is per location; without one the server reports the RPC as
+    // unavailable even though this project's copy is registered.
+    const at = () =>
+      context.location ? { location: context.location } : undefined;
+
+    const abort = new AbortController();
+    let inFlight = false;
+    let disposed = false;
+    let unsubscribe: (() => void) | null = null;
+
+    // Subscriptions do not survive a server restart, so they are re-armed
+    // against the current client after each successful poll.
+    const resubscribe = (): void => {
+      if (disposed || unsubscribe) return;
+      unsubscribe = subscribe(rpc(), () => void refresh(), abort.signal);
+    };
+
+    const unsubscribeEvents = (): void => {
+      unsubscribe?.();
+      unsubscribe = null;
+    };
+
+    const refresh = async (): Promise<void> => {
+      if (disposed || inFlight) return;
+      inFlight = true;
+
+      try {
+        const snapshot = (await rpc().status({}, at())) as StatusSnapshot;
+        update((draft) => {
+          draft.snapshot = snapshot;
+          draft.lines = sidebarLines(snapshot, Date.now());
+          draft.ready = snapshot.node.phase === "ready";
+          draft.reason = null;
+        });
+        resubscribe();
+      } catch (error) {
+        const reason = describe(error);
+        unsubscribeEvents();
+        update((draft) => {
+          draft.snapshot = null;
+          draft.reason = reason;
+          draft.lines = ["XERJ  ○ offline", reason];
+          draft.ready = false;
+        });
+      } finally {
+        inFlight = false;
+      }
+    };
+
+    const showStatus = async (): Promise<void> => {
+      await refresh();
+      // Re-running the command closes the panel it opened.
+      if (context.ui.panel.current()?.name === PANEL_NAME) {
+        context.ui.panel.close();
+        return;
+      }
+      if (context.ui.panel.open(PANEL_NAME)) return;
+
+      await context.ui.dialog.alert({
+        title: "XERJ",
+        message: statusText(state.snapshot, state.lines),
+      });
+    };
+
+    const reindex = async (): Promise<void> => {
+      try {
+        const result = (await rpc().reindex({}, at())) as { queued?: boolean };
+        context.ui.toast.show({
+          message: result.queued
+            ? "XERJ reindex queued"
+            : "XERJ indexing is disabled",
+          variant: result.queued ? "success" : "info",
+        });
+      } catch {
+        context.ui.toast.show({
+          message: "XERJ is not available",
+          variant: "error",
+        });
+      }
+    };
+
+    const promptFor = async (title: string, description: string): Promise<string> => {
+      const answer = await context.ui.dialog.prompt({ title, description });
+      return answer?.trim() ?? "";
+    };
+
+    const remember = async (prefill?: string): Promise<void> => {
+      const text =
+        prefill?.trim() ||
+        (await promptFor("Remember in XERJ", "Durable fact or decision"));
+      if (!text) return;
+
+      try {
+        const result = (await rpc().remember({ text }, at())) as {
+          id: string;
+          created: boolean;
+        };
+        context.ui.toast.show({
+          message: result.created
+            ? `Remembered as ${result.id}`
+            : `Already remembered as ${result.id}`,
+          variant: result.created ? "success" : "info",
+        });
+      } catch {
+        context.ui.toast.show({
+          message: "XERJ memory is not available",
+          variant: "error",
+        });
+      }
+    };
+
+    const search = async (prefill?: string): Promise<void> => {
+      const query =
+        prefill?.trim() ||
+        (await promptFor("Search XERJ", "What to look for"));
+      if (!query) return;
+
+      try {
+        const result = (await rpc().search({ query }, at())) as {
+          text: string;
+          hits: number;
+          bytes: number;
+        };
+        await context.ui.dialog.alert({
+          title: [
+            "XERJ search",
+            `${result.hits} ${result.hits === 1 ? "hit" : "hits"}`,
+          ].join(" · "),
+          message:
+            result.hits === 0 ? "No passages matched." : clip(result.text),
+        });
+      } catch {
+        context.ui.toast.show({
+          message: "XERJ search is not available",
+          variant: "error",
+        });
+      }
+    };
+
+    void refresh();
+    // Events arrive on the first success; the timer covers host or node gaps.
+    const timer = setInterval(() => void refresh(), FALLBACK_POLL_MS);
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "xerj.status",
+          title: "XERJ status",
+          description: "Open the XERJ details panel",
+          group: "XERJ",
+          palette: true,
+          slash: { name: "xerj", arguments: true },
+          run: async (input) => {
+            const text = (input ?? "").trim();
+            if (text.length === 0 || text === "status") return showStatus();
+
+            const [head, ...rest] = text.split(/\s+/);
+            const argument = rest.join(" ").trim();
+
+            if (head === "reindex") return reindex();
+            if (head === "remember") return remember(argument);
+            if (head === "search") return search(argument);
+
+            context.ui.toast.show({
+              message: `Unknown XERJ command: ${head}`,
+              variant: "warning",
+            });
+          },
+        },
+        {
+          id: "xerj.close",
+          title: "Close XERJ panel",
+          description: "Close the XERJ details panel",
+          group: "XERJ",
+          bind: "escape",
+          enabled: () => context.ui.panel.current()?.name === PANEL_NAME,
+          run: () => context.ui.panel.close(),
+        },
+        {
+          id: "xerj.reindex",
+          title: "XERJ reindex",
+          description: "Queue an incremental reindex of this project",
+          group: "XERJ",
+          palette: true,
+          slash: { name: "xerj-reindex" },
+          enabled: () => state.ready,
+          run: () => reindex(),
+        },
+        {
+          id: "xerj.remember",
+          title: "XERJ remember",
+          description: "Store a durable project fact in XERJ memory",
+          group: "XERJ",
+          palette: true,
+          slash: { name: "xerj-remember", arguments: true },
+          enabled: () => state.ready,
+          run: (input) => remember(input),
+        },
+        {
+          id: "xerj.search",
+          title: "XERJ search",
+          description: "Search the project index and show cited passages",
+          group: "XERJ",
+          palette: true,
+          slash: { name: "xerj-search", arguments: true },
+          enabled: () => state.ready,
+          run: (input) => search(input),
+        },
+      ],
+    }));
+
+    const detachSidebar = context.ui.slot({
+      append: "sidebar.content",
+      render: () => (
+        <box flexDirection="column">
+          {state.lines.map((line) => {
+            const color = line.startsWith("XERJ")
+              ? context.theme.text.base
+              : context.theme.text.muted;
+            return <text fg={color}>{line}</text>;
+          })}
+        </box>
+      ),
+    });
+
+    const detachPanel = context.ui.slot({
+      append: "session.panel",
+      render: (input) => {
+        if (input.name !== PANEL_NAME) return null;
+
+        const snapshot = state.snapshot;
+        const sections = snapshot ? panelSections(snapshot, Date.now()) : [];
+
+        return (
+          <box flexDirection="column">
+            <scrollbox flexDirection="column">
+              {sections.map((section) => (
+                <box flexDirection="column" marginBottom={1}>
+                  <text fg={context.theme.text.base}>{section.title}</text>
+                  {section.lines.map((line) => (
+                    <text fg={context.theme.text.muted}>{line}</text>
+                  ))}
+                </box>
+              ))}
+              {sections.length === 0 ? (
+                <text fg={context.theme.text.faint}>
+                  {state.reason ?? "waiting for the XERJ server part"}
+                </text>
+              ) : null}
+            </scrollbox>
+            <box
+              flexDirection="row"
+              justifyContent="space-between"
+              marginTop={1}
+            >
+              <text fg={context.theme.text.faint}>esc or /xerj closes</text>
+              <box
+                border
+                borderColor={context.theme.border.base}
+                paddingLeft={1}
+                paddingRight={1}
+                onMouseDown={() => input.close()}
+              >
+                <text fg={context.theme.text.base}>✕ close</text>
+              </box>
+            </box>
+          </box>
+        );
+      },
+    });
+
+    return () => {
+      disposed = true;
+      abort.abort();
+      clearInterval(timer);
+      unsubscribeEvents();
+      detachPanel();
+      detachSidebar();
+    };
+  },
+});
+
+type EventSource = {
+  events?: {
+    on?: (
+      name: "updated",
+      handler: () => void,
+      options: { signal: AbortSignal },
+    ) => () => void;
+  };
+};
+
+function subscribe(
+  rpc: EventSource,
+  handler: () => void,
+  signal: AbortSignal,
+): () => void {
+  try {
+    return rpc.events?.on?.("updated", handler, { signal }) ?? (() => {});
+  } catch {
+    return () => {};
+  }
+}
+
+function statusText(
+  snapshot: StatusSnapshot | null,
+  lines: ReadonlyArray<string>,
+): string {
+  if (!snapshot) return lines.join("\n");
+
+  return panelSections(snapshot, Date.now())
+    .flatMap((section) => [section.title, ...section.lines])
+    .join("\n");
+}
+
+// Short, single-line failure reason for the sidebar and the empty panel.
+function describe(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  const first = text.split("\n")[0]?.trim();
+  if (!first) return "the XERJ server part did not answer";
+  return first.length > 72 ? `${first.slice(0, 71)}…` : first;
+}
+
+function clip(text: string): string {
+  if (text.length <= SEARCH_CLIP) return text;
+  return `${text.slice(0, SEARCH_CLIP)}\n…`;
+}

package/src/ui/format.ts

@@ -0,0 +1,234 @@
+// Presentation only: every function here turns a status snapshot into text.
+// No I/O, no RPC, so the TUI stays thin and the formatting stays testable.
+
+import type { StatusSnapshot } from "../rpc.ts";
+
+export interface PanelSection {
+  readonly title: string;
+  readonly lines: ReadonlyArray<string>;
+}
+
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB"] as const;
+const THOUSAND = 1000;
+
+export function formatBytes(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return "0 B";
+
+  let amount = value;
+  let unit = 0;
+  while (amount >= 1024 && unit < BYTE_UNITS.length - 1) {
+    amount /= 1024;
+    unit += 1;
+  }
+
+  // Whole bytes stay whole; scaled units keep one decimal below 100.
+  const digits = unit === 0 || amount >= 100 ? 0 : 1;
+  return `${amount.toFixed(digits)} ${BYTE_UNITS[unit]}`;
+}
+
+export function formatCount(value: number): string {
+  if (!Number.isFinite(value)) return "0";
+  return Math.round(value).toLocaleString("en-US");
+}
+
+export function formatTokens(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return "~0";
+  if (value < THOUSAND) return `~${Math.round(value)}`;
+
+  if (value < THOUSAND * THOUSAND) {
+    return `~${(value / THOUSAND).toFixed(1)}K`;
+  }
+  return `~${(value / (THOUSAND * THOUSAND)).toFixed(1)}M`;
+}
+
+export function formatPercent(ratio: number): string {
+  if (!Number.isFinite(ratio) || ratio <= 0) return "0%";
+  return `${Math.round(ratio * 100)}%`;
+}
+
+/** Compact age; `null` is "never" and the first ten seconds are "just now". */
+export function formatAge(now: number, at: number | null): string {
+  if (at === null || !Number.isFinite(at)) return "never";
+
+  const seconds = Math.max(0, Math.round((now - at) / THOUSAND));
+  if (seconds < 10) return "just now";
+  if (seconds < 60) return `${seconds}s ago`;
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+/** Four lines for the sidebar slot. */
+export function sidebarLines(snapshot: StatusSnapshot, now: number): string[] {
+  const index = snapshot.index;
+  const usage = snapshot.usage;
+  const records =
+    index.lastRecords === null
+      ? "no runs"
+      : `${formatCount(index.lastRecords)} records`;
+
+  return [
+    `XERJ  ${marker(snapshot)} ${headline(snapshot)}`,
+    [
+      `q ${formatCount(usage.queries)}`,
+      `hit ${formatPercent(usage.hitRate)}`,
+      `${formatTokens(usage.tokensSaved)} tok saved`,
+    ].join("  "),
+    `idx ${formatAge(now, index.lastRunAt)} · ${records}`,
+    "▸ /xerj for details",
+  ];
+}
+
+/** Every block of the details panel, in display order. */
+export function panelSections(snapshot: StatusSnapshot, now: number): PanelSection[] {
+  const { node, binary, index, memory, usage } = snapshot;
+
+  return [
+    {
+      title: "Node",
+      lines: [
+        [
+          node.phase,
+          node.spawned ? "spawned" : "attached",
+          node.baseUrl ?? "no address",
+        ].join(" · "),
+        node.serverVersion === null ? "server unknown" : `server ${node.serverVersion}`,
+      ],
+    },
+    {
+      title: "Binary",
+      lines: [
+        `${binary.version ?? "not installed"}${targetSuffix(binary.target)}`,
+        binary.path ?? "managed download",
+      ],
+    },
+    {
+      title: "Index",
+      lines: [
+        `${index.state} · ${index.prefix}`,
+        [
+          `${formatCount(index.docs)} docs`,
+          formatBytes(index.bytes),
+          `${index.indices} ${plural(index.indices, "index", "indices")}`,
+        ].join(" · "),
+        [
+          `last run ${formatAge(now, index.lastRunAt)}`,
+          `generation ${index.lastGeneration ?? "—"}`,
+          `${index.lastRecords ?? 0} records`,
+        ].join(" · "),
+      ],
+    },
+    {
+      title: "Datasets",
+      lines:
+        index.datasets.length === 0
+          ? ["none yet"]
+          : index.datasets.map(
+              (dataset) =>
+                `${dataset.name}  ${formatCount(dataset.docs)} docs · ` +
+                `${formatBytes(dataset.bytes)}`,
+            ),
+    },
+    ...(snapshot.brains.length === 0
+      ? []
+      : [
+          {
+            title: "Brains",
+            lines: snapshot.brains.map((brain) =>
+              [
+                `${brain.name}  ${formatCount(brain.docs)} docs`,
+                `${brain.edges} ${plural(brain.edges, "edge", "edges")}`,
+                formatAge(now, brain.lastRunAt),
+                brain.error ?? "",
+              ]
+                .filter((part) => part.length > 0)
+                .join(" · "),
+            ),
+          },
+        ]),
+    {
+      title: "Memory",
+      lines: [
+        [
+          `${formatCount(memory.count)} ${plural(memory.count, "entry", "entries")}`,
+          memory.namespace,
+        ].join(" · "),
+      ],
+    },
+    {
+      title: "Usage",
+      lines: [
+        [
+          `${formatCount(usage.queries)} queries`,
+          `${formatPercent(usage.hitRate)} hit`,
+          `${formatCount(usage.hits)} hits`,
+        ].join(" · "),
+        [
+          `${formatTokens(usage.tokensSaved)} tokens saved`,
+          `${formatBytes(usage.savedBytes)} of ` +
+            `${formatBytes(usage.baselineBytes)} baseline`,
+        ].join(" · "),
+        `${formatBytes(usage.bytesReturned)} returned · ${formatBytes(usage.bytesRead)} read`,
+      ],
+    },
+    {
+      title: "Counters",
+      lines: [
+        `${formatCount(snapshot.counters.indexRuns)} index runs · ` +
+          `${formatCount(snapshot.counters.injectedTurns)} injections`,
+        `${formatCount(snapshot.counters.nodeSpawns)} spawns · ` +
+          `${formatCount(snapshot.counters.http429)} rate-limited · ` +
+          `${formatCount(snapshot.counters.rpcCalls)} rpc calls`,
+      ],
+    },
+    {
+      title: "Top cited",
+      lines:
+        usage.topFiles.length === 0
+          ? ["none yet"]
+          : usage.topFiles.map(
+              (file) => `${file.path} ×${file.citations} · ${formatBytes(file.bytes)}`,
+            ),
+    },
+    {
+      title: "Health",
+      lines: healthLines(snapshot),
+    },
+  ];
+}
+
+function healthLines(snapshot: StatusSnapshot): string[] {
+  const lines = [
+    ...snapshot.warnings.map((warning) => `warn: ${warning}`),
+    ...snapshot.recent,
+    ...snapshot.errors.map((error) => `error: ${error}`),
+  ];
+
+  return lines.length === 0 ? ["no warnings"] : lines.slice(-6);
+}
+
+function marker(snapshot: StatusSnapshot): string {
+  return snapshot.node.phase === "ready" ? "●" : "○";
+}
+
+function headline(snapshot: StatusSnapshot): string {
+  const index = snapshot.index;
+  if (snapshot.node.phase !== "ready") {
+    return snapshot.node.phase === "starting" ? "starting" : snapshot.node.phase;
+  }
+  if (index.docs === 0) return "ready · not indexed yet";
+  return `ready · ${formatCount(index.docs)} docs · ${formatBytes(index.bytes)}`;
+}
+
+function targetSuffix(target: string | null): string {
+  return target === null ? "" : ` · ${target}`;
+}
+
+function plural(count: number, one: string, many: string): string {
+  return count === 1 ? one : many;
+}