catherd-cli 0.2.1 → 1.0.0

package/src/entry/tui/widgets/dialog.tsx

@@ -0,0 +1,68 @@
+// Adapted from anomalyco/opencode packages/tui/src/ui/dialog.tsx (MIT, © 2025 opencode);
+// see THIRD_PARTY_NOTICES.md.
+import { useTerminalDimensions } from "@opentui/react";
+import type { ReactNode } from "react";
+import { useTone, useUi } from "../providers/theme.tsx";
+import { DIALOG_WIDTH, type DialogSize } from "../theme.ts";
+import { Line } from "./line.tsx";
+
+/** The panel's inner width: its size, clamped to the terminal less a margin, less the padding. */
+const dialogInner = (size: DialogSize, termWidth: number): number =>
+  Math.max(10, Math.min(DIALOG_WIDTH[size], termWidth - 2) - 4);
+
+/** The rows a quarter down the screen leaves for `rows`: the height less the top padding, the
+ * blank line, the title, the gap under it and the blank line at the bottom. */
+export const dialogRows = (termHeight: number): number =>
+  Math.max(1, termHeight - Math.floor(termHeight / 4) - 4);
+
+/**
+ * Spec §9.3: a raised panel over a dimmed backdrop, a quarter down the screen, 60, 88 or 116 columns
+ * wide, with no border; the title bold on the left and a muted `esc` on the right. `rows` returns one
+ * node per line, each `inner` columns wide (Line pads them); the panel pads every line with spaces on
+ * both sides, so it hides what is beneath even without colour.
+ */
+export function Dialog(props: { title: string; size?: DialogSize; rows: (inner: number) => ReactNode[] }) {
+  const dims = useTerminalDimensions();
+  const ui = useUi();
+  const tone = useTone();
+  const size = props.size ?? "medium";
+  const inner = dialogInner(size, dims.width);
+  const lines: ReactNode[] = [
+    <Line key="top" width={inner} parts={[]} />,
+    <Line
+      key="title"
+      width={inner}
+      parts={[
+        { text: props.title, bold: true },
+        { text: " ".repeat(Math.max(1, inner - Bun.stringWidth(props.title) - 3)) },
+        { text: "esc", tone: "muted" },
+      ]}
+    />,
+    <Line key="gap" width={inner} parts={[]} />,
+    ...props.rows(inner),
+    <Line key="bottom" width={inner} parts={[]} />,
+  ];
+  return (
+    <box
+      position="absolute"
+      top={0}
+      left={0}
+      zIndex={3000}
+      width={dims.width}
+      height={dims.height}
+      alignItems="center"
+      paddingTop={Math.floor(dims.height / 4)}
+      backgroundColor={ui.color ? `${tone("backdrop")}99` : undefined}
+    >
+      <box width={inner + 4} flexDirection="column" backgroundColor={tone("surfaceRaised")}>
+        {lines.map((line, i) => (
+          <box key={i} flexDirection="row" height={1}>
+            <text>{"  "}</text>
+            {line}
+            <text>{"  "}</text>
+          </box>
+        ))}
+      </box>
+    </box>
+  );
+}

package/src/entry/tui/widgets/line.tsx

@@ -0,0 +1,92 @@
+import { RGBA, TextAttributes } from "@opentui/core";
+import { useTone, useUi } from "../providers/theme.tsx";
+import { ascii, truncateEnd, width as widthOf } from "../text.ts";
+import type { Token } from "../theme.ts";
+
+/** One run of text on a line, in a token's colour. */
+export interface Part {
+  text: string;
+  tone?: Token;
+  bold?: boolean;
+}
+
+/** The parts cut to `max` columns at the end (an ellipsis on the last one kept). */
+export function clip(parts: Part[], max: number, plain: boolean): Part[] {
+  const out: Part[] = [];
+  let used = 0;
+  for (const p of parts) {
+    const w = widthOf(p.text);
+    if (used + w <= max) {
+      out.push(p);
+      used += w;
+      continue;
+    }
+    const room = max - used;
+    if (room > 0) out.push({ ...p, text: truncateEnd(p.text, room, plain) });
+    break;
+  }
+  return out;
+}
+
+/**
+ * The one line primitive every row is drawn with: exactly `width` columns. A selected line is filled
+ * with the accent and bold (spec §9.3), or drawn in reverse video without colour; under --plain every
+ * character is ASCII.
+ */
+export function Line(props: {
+  parts: Part[];
+  width: number;
+  selected?: boolean;
+  dim?: boolean;
+  /**
+   * Paints every cell, spaces included, so nothing beneath shows through (a toast over the tabs): the
+   * raised surface with colour, reverse video without, since a plain space paints nothing.
+   */
+  opaque?: boolean;
+}) {
+  const ui = useUi();
+  const tone = useTone();
+  const parts = clip(
+    ui.plain ? props.parts.map((p) => ({ ...p, text: ascii(p.text) })) : props.parts,
+    props.width,
+    ui.plain,
+  );
+  const used = parts.reduce((n, p) => n + widthOf(p.text), 0);
+  const pad = " ".repeat(Math.max(0, props.width - used));
+  const sel = props.selected === true;
+  const fg = (p: Part) =>
+    sel ? tone("selectionText") : props.dim ? tone("muted") : p.tone ? tone(p.tone) : undefined;
+  // without colour, the terminal's own default background (SGR 49, no colour) makes a space paint
+  const bg = sel
+    ? tone("selection")
+    : props.opaque
+      ? ui.color
+        ? tone("surfaceRaised")
+        : RGBA.defaultBackground()
+      : undefined;
+  const inverse = (sel || props.opaque === true) && !ui.color ? TextAttributes.INVERSE : 0;
+  const attrs = (p: Part) => (sel || p.bold ? TextAttributes.BOLD : 0) | inverse;
+  return (
+    <text wrapMode="none">
+      {parts.map((p, i) => (
+        <span key={i} fg={fg(p)} bg={bg} attributes={attrs(p)}>
+          {p.text}
+        </span>
+      ))}
+      <span bg={bg} attributes={inverse}>
+        {pad}
+      </span>
+    </text>
+  );
+}
+
+/** A full-width rule (`─`, or `-` in plain). */
+export function Rule(props: { width: number }) {
+  const ui = useUi();
+  const tone = useTone();
+  return (
+    <text wrapMode="none" fg={tone("border")}>
+      {(ui.plain ? "-" : "─").repeat(Math.max(0, props.width))}
+    </text>
+  );
+}

package/src/entry/tui/widgets/list.tsx

@@ -0,0 +1,196 @@
+import type { InputRenderable } from "@opentui/core";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { useBack } from "../providers/app.tsx";
+import { useCommandLayer } from "../providers/keymap.tsx";
+import { useTone, useUi } from "../providers/theme.tsx";
+import { glyph } from "../theme.ts";
+import { Line } from "./line.tsx";
+
+export interface ListItem {
+  key: string;
+  /** headings and continuation lines are skipped by the cursor */
+  selectable: boolean;
+  render(selected: boolean, width: number): ReactNode;
+}
+
+export interface Window {
+  top: number;
+  /** rows hidden above and below the window */
+  above: number;
+  below: number;
+}
+
+const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n));
+
+/**
+ * Which rows of `total` fit in `height` so that `index` shows, moving no more than needed from `top`.
+ * With 3 rows or more, a hint line (`↑ 3 more`) takes the first or the last row when rows are hidden there.
+ */
+export function windowOf(total: number, index: number, height: number, top: number): Window {
+  if (total <= height) return { top: 0, above: 0, below: 0 };
+  const i = clamp(index, 0, total - 1);
+  const maxTop = total - height;
+  let t = clamp(top, 0, maxTop);
+  if (height >= 3) {
+    const first = t + (t > 0 ? 1 : 0);
+    const last = t + height - 1 - (t < maxTop ? 1 : 0);
+    if (i < first) t = i === 0 ? 0 : i - 1;
+    else if (i > last) t = i === total - 1 ? maxTop : i - height + 2;
+  } else if (i < t) t = i;
+  else if (i > t + height - 1) t = i - height + 1;
+  t = clamp(t, 0, maxTop);
+  return height >= 3 ? { top: t, above: t, below: maxTop - t } : { top: t, above: 0, below: 0 };
+}
+
+/**
+ * The selectable row `by` selectable rows away from row `from` (clamped to the ends). From a row that
+ * cannot be selected, the next selectable row is one step down and the previous one a step up; `by` 0
+ * snaps to the next one (else the last).
+ */
+export function step(items: readonly { selectable: boolean }[], from: number, by: number): number {
+  const sel = items.flatMap((it, i) => (it.selectable ? [i] : []));
+  if (sel.length === 0) return -1;
+  const at = sel.indexOf(from);
+  if (at >= 0) return sel[clamp(at + by, 0, sel.length - 1)] as number;
+  const next = sel.findIndex((i) => i > from);
+  if (by === 0) return sel[next < 0 ? sel.length - 1 : next] as number;
+  const pos = by > 0 ? (next < 0 ? sel.length - 1 : next + by - 1) : (next < 0 ? sel.length : next) + by;
+  return sel[clamp(pos, 0, sel.length - 1)] as number;
+}
+
+/**
+ * A view's selected row: `selected` is what this render draws, `current()` what a key handler must read
+ * (a key in the same tick may have moved it already).
+ */
+export function useSelected(): {
+  selected: string | null;
+  select(key: string): void;
+  current(): string | null;
+} {
+  const [selected, setSelected] = useState<string | null>(null);
+  const ref = useRef<string | null>(null);
+  ref.current = selected;
+  return {
+    selected,
+    select(key) {
+      ref.current = key;
+      setSelected(key);
+    },
+    current: () => ref.current,
+  };
+}
+
+/**
+ * A list or tree pane (spec §9.2 lists: arrows plus j/k, paging, Home/End, `/` filter). Controlled: the
+ * view owns the selected key and the filter text; the list moves them and draws the visible window with
+ * `↑ n more` / `↓ n more` hints instead of a scrollbar.
+ */
+export function List(props: {
+  items: ListItem[];
+  selected: string | null;
+  onSelect(key: string): void;
+  width: number;
+  height: number;
+  /** the filter text, null when no filter is open */
+  filter?: string | null;
+  onFilter?(text: string | null): void;
+  /** the muted line shown when there are no rows */
+  empty: string;
+}) {
+  const ui = useUi();
+  const tone = useTone();
+  const input = useRef<InputRenderable>(null);
+  const [top, setTop] = useState(0);
+  // the command that opens the filter is drawn at once (useCommandLayer), so this runs before the next key
+  const [focusTick, setFocusTick] = useState(0);
+  useEffect(() => {
+    if (focusTick > 0) input.current?.focus();
+  }, [focusTick]);
+  const filtering = props.filter !== undefined && props.filter !== null;
+  const bodyHeight = Math.max(1, props.height - (filtering ? 1 : 0));
+  const indexOf = (key: string | null) => {
+    const i = props.items.findIndex((it) => it.key === key);
+    return i < 0 || !props.items[i]?.selectable ? step(props.items, Math.max(0, i), 0) : i;
+  };
+  const index = indexOf(props.selected);
+  // the row a key handler moves from: the one the last key chose, which may not be drawn yet
+  const selectedRef = useRef(props.selected);
+  selectedRef.current = props.selected;
+  const choose = (i: number) => {
+    const it = props.items[i];
+    if (!it) return;
+    selectedRef.current = it.key;
+    props.onSelect(it.key);
+  };
+  const w = windowOf(props.items.length, Math.max(0, index), bodyHeight, top);
+  useEffect(() => {
+    if (w.top !== top) setTop(w.top);
+  }, [w.top, top]);
+  // the cursor snaps to a selectable row, judged on the selection now: this effect can run after a key
+  // already moved it (a key that lands between a draw and its effects), and must not take that back
+  useEffect(() => {
+    const it = props.items[indexOf(selectedRef.current)];
+    if (it && it.key !== selectedRef.current) choose(indexOf(selectedRef.current));
+  });
+  const move = (by: number) => choose(step(props.items, Math.max(0, indexOf(selectedRef.current)), by));
+  const page = Math.max(1, bodyHeight - 2);
+  useCommandLayer("list", {
+    "list.up": () => move(-1),
+    "list.down": () => move(1),
+    "list.pageUp": () => move(-page),
+    "list.pageDown": () => move(page),
+    "list.first": () => choose(step(props.items, 0, 0)),
+    "list.last": () => choose(step(props.items, props.items.length - 1, 0)),
+    ...(props.onFilter
+      ? {
+          "list.filter": () => {
+            props.onFilter?.(props.filter ?? "");
+            setFocusTick((n) => n + 1);
+          },
+        }
+      : {}),
+  });
+  useCommandLayer("filter", { "filter.accept": () => input.current?.blur() });
+  useBack(filtering, "input", () => {
+    input.current?.blur();
+    props.onFilter?.(null);
+  });
+  const rows: ReactNode[] = [];
+  const visible = props.items.slice(w.top, w.top + bodyHeight);
+  visible.forEach((it, i) => {
+    const hintAbove = i === 0 && w.above > 0;
+    const hintBelow = i === visible.length - 1 && w.below > 0;
+    if (hintAbove || hintBelow) {
+      const n = hintAbove ? w.above + 1 : w.below + 1;
+      rows.push(
+        <Line
+          key={`hint-${hintAbove ? "up" : "down"}`}
+          width={props.width}
+          parts={[{ text: `  ${glyph(hintAbove ? "up" : "down", ui.plain)} ${n} more`, tone: "muted" }]}
+        />,
+      );
+      return;
+    }
+    rows.push(<box key={it.key}>{it.render(w.top + i === index, props.width)}</box>);
+  });
+  if (props.items.length === 0)
+    rows.push(<Line key="empty" width={props.width} parts={[{ text: `  ${props.empty}`, tone: "muted" }]} />);
+  const matches = props.items.filter((it) => it.selectable).length;
+  return (
+    <box flexDirection="column" width={props.width} height={props.height}>
+      {filtering ? (
+        <box flexDirection="row" width={props.width} height={1}>
+          <text fg={tone("accent")}>{" / "}</text>
+          <input
+            ref={input}
+            value={props.filter ?? ""}
+            onInput={(v: string) => props.onFilter?.(v)}
+            width={Math.max(1, props.width - 18)}
+          />
+          <text fg={tone("muted")}>{` ${matches} ${matches === 1 ? "match" : "matches"}`.padEnd(15)}</text>
+        </box>
+      ) : null}
+      {rows}
+    </box>
+  );
+}

package/src/entry/tui/widgets/spinner.tsx

@@ -0,0 +1,49 @@
+// Adapted from anomalyco/opencode packages/tui/src/component/spinner.tsx and startup-loading.tsx
+// (MIT, © 2025 opencode); see THIRD_PARTY_NOTICES.md.
+import { useEffect, useState } from "react";
+import { useApp } from "../providers/app.tsx";
+import { useTone, useUi } from "../providers/theme.tsx";
+import { ascii } from "../text.ts";
+import { SPINNER } from "../theme.ts";
+
+/**
+ * Spec §9.3 motion: true once `active` has lasted SPINNER.showAfterMs, and then for at least
+ * SPINNER.minShowMs, so a quick check never flickers.
+ */
+export function useDelayedPresence(active: boolean): boolean {
+  const { clock } = useApp();
+  const [shownAt, setShownAt] = useState<number | null>(null);
+  useEffect(() => {
+    if (active && shownAt === null) {
+      const h = clock.setTimeout(() => setShownAt(clock.now()), SPINNER.showAfterMs);
+      return () => clock.clearTimeout(h);
+    }
+    if (!active && shownAt !== null) {
+      const left = SPINNER.minShowMs - (clock.now() - shownAt);
+      if (left <= 0) {
+        setShownAt(null);
+        return;
+      }
+      const h = clock.setTimeout(() => setShownAt(null), left);
+      return () => clock.clearTimeout(h);
+    }
+    return undefined;
+  }, [active, shownAt, clock]);
+  return shownAt !== null;
+}
+
+/** A braille spinner and what it waits on; a still `⋯` under reduced motion (spec §9.3). */
+export function Spinner(props: { label: string }) {
+  const { clock } = useApp();
+  const ui = useUi();
+  const tone = useTone();
+  const [frame, setFrame] = useState(0);
+  useEffect(() => {
+    if (ui.reducedMotion) return;
+    const h = clock.setInterval(() => setFrame((f) => f + 1), SPINNER.ms);
+    return () => clock.clearInterval(h);
+  }, [clock, ui.reducedMotion]);
+  const frames = ui.plain ? SPINNER.plainFrames : SPINNER.frames;
+  const g = ui.reducedMotion ? SPINNER.still[ui.plain ? 1 : 0] : frames[frame % frames.length];
+  return <text fg={tone("muted")}>{`${g} ${ui.plain ? ascii(props.label) : props.label}`}</text>;
+}

package/src/entry/tui/widgets/toast.tsx

@@ -0,0 +1,62 @@
+// Adapted from anomalyco/opencode packages/tui/src/ui/toast.tsx (MIT, © 2025 opencode);
+// see THIRD_PARTY_NOTICES.md.
+import { useTerminalDimensions } from "@opentui/react";
+import { useToasts } from "../providers/toast.tsx";
+import { useUi } from "../providers/theme.tsx";
+import { truncateEnd, wrap } from "../text.ts";
+import { glyph, type Token } from "../theme.ts";
+import { Line } from "./line.tsx";
+
+const TONE: Record<string, Token> = { info: "info", success: "success", warning: "warning", error: "error" };
+
+/** Lines of a toast's message kept before the rest is cut; a fix command always shows in full. */
+const MESSAGE_LINES = 3;
+
+/**
+ * Spec §9.3: the current toast at the top right, with a `┃` bar in its colour and the queue's length.
+ * The message wraps to three lines; a fix command wraps in full on muted lines under it.
+ */
+export function ToastHost() {
+  const { current, queued } = useToasts();
+  const ui = useUi();
+  const dims = useTerminalDimensions();
+  if (!current) return null;
+  const bar = glyph("bar", ui.plain);
+  const max = Math.max(1, Math.min(60, dims.width - 6) - 4);
+  const said = wrap(`${current.message}${queued ? `  +${queued} more` : ""}`, max);
+  const message = said.slice(0, MESSAGE_LINES);
+  if (said.length > MESSAGE_LINES)
+    message[MESSAGE_LINES - 1] = truncateEnd(
+      `${message[MESSAGE_LINES - 1]} ${said[MESSAGE_LINES]}`,
+      max,
+      ui.plain,
+    );
+  const fix = current.fix ? wrap(current.fix, max) : [];
+  const text = Math.max(...[...message, ...fix].map((l) => Bun.stringWidth(l)));
+  const w = text + 4;
+  const line = (t: string, muted: boolean, i: number) => (
+    <Line
+      key={i}
+      width={w}
+      opaque
+      parts={[
+        { text: `${bar} `, tone: TONE[current.variant] },
+        { text: t.padEnd(text + t.length - Bun.stringWidth(t)), tone: muted ? "muted" : undefined },
+        { text: ` ${bar}`, tone: TONE[current.variant] },
+      ]}
+    />
+  );
+  return (
+    <box
+      position="absolute"
+      top={1}
+      left={Math.max(0, dims.width - w - 2)}
+      zIndex={4000}
+      width={w}
+      height={message.length + fix.length}
+      flexDirection="column"
+    >
+      {[...message.map((t, i) => line(t, false, i)), ...fix.map((t, i) => line(t, true, message.length + i))]}
+    </box>
+  );
+}

package/src/infra/assets.ts

@@ -0,0 +1,4 @@
+import { fileURLToPath } from "node:url";
+
+/** A file shipped in the package, such as `catalog/models.json`; catherd ships its sources unbuilt. */
+export const assetPath = (rel: string): string => fileURLToPath(new URL(`../../${rel}`, import.meta.url));