catherd-cli 0.2.0 → 1.0.0

package/src/entry/tui/theme.ts

@@ -0,0 +1,139 @@
+import type { State } from "../glyphs.ts";
+
+/** Spec §9.3: the 16 semantic tokens every widget paints with. */
+export const TOKENS = [
+  "text",
+  "muted",
+  "accent",
+  "accentText",
+  "surface",
+  "surfaceRaised",
+  "backdrop",
+  "border",
+  "success",
+  "warning",
+  "error",
+  "info",
+  "selection",
+  "selectionText",
+  "diffAdd",
+  "diffDel",
+] as const;
+export type Token = (typeof TOKENS)[number];
+export type Palette = Record<Token, string>;
+export type ThemeMode = "dark" | "light";
+
+/**
+ * Accent ginger `#E8833A` on dark and `#B45309` on light (spec §9.3); every colour that carries text
+ * keeps 4.5:1 against both surfaces (test/entry/tui/theme.test.ts). The screen itself keeps the
+ * terminal's own background; `surface` is only what text on the accent fill contrasts with.
+ */
+export const PALETTES: Record<ThemeMode, Palette> = {
+  dark: {
+    text: "#EEEEEE",
+    muted: "#8A8A8A",
+    accent: "#E8833A",
+    accentText: "#0A0A0A",
+    surface: "#0A0A0A",
+    surfaceRaised: "#1E1E1E",
+    backdrop: "#000000",
+    border: "#484848",
+    success: "#7FD88F",
+    warning: "#F5A742",
+    error: "#E06C75",
+    info: "#56B6C2",
+    selection: "#E8833A",
+    selectionText: "#0A0A0A",
+    diffAdd: "#4FD6BE",
+    diffDel: "#E06C75",
+  },
+  light: {
+    text: "#1A1A1A",
+    muted: "#6B6B6B",
+    accent: "#B45309",
+    accentText: "#FFFFFF",
+    surface: "#FFFFFF",
+    surfaceRaised: "#F7F7F7",
+    backdrop: "#000000",
+    border: "#B8B8B8",
+    success: "#2F7D46",
+    warning: "#8A6116",
+    error: "#C22D33",
+    info: "#256F7B",
+    selection: "#B45309",
+    selectionText: "#FFFFFF",
+    diffAdd: "#1E725C",
+    diffDel: "#B42A3E",
+  },
+};
+
+/** How this terminal is drawn: `plain` is ASCII only, `color` false paints nothing (NO_COLOR). */
+export interface Ui {
+  plain: boolean;
+  color: boolean;
+  reducedMotion: boolean;
+  mode: ThemeMode;
+}
+
+type Env = Record<string, string | undefined>;
+
+/** The first locale variable that is set decides; with none set the terminal is taken to speak UTF-8. */
+function utf8(env: Env): boolean {
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG;
+  return !locale || /utf-?8/i.test(locale);
+}
+
+/**
+ * Spec §9.3: `NO_COLOR` and `--plain` (ASCII glyphs, no colour). Reads only `rawArgs` and `env`, never
+ * the terminal, so it answers the same on every machine. OpenTUI downsamples true colour itself.
+ */
+export function detectUi(rawArgs: readonly string[], env: Env): Omit<Ui, "mode"> {
+  const dumb = env.TERM === "dumb";
+  const plain = rawArgs.includes("--plain") || env.TERM === "linux" || dumb || !utf8(env);
+  return {
+    plain,
+    color: !rawArgs.includes("--plain") && !dumb && !env.NO_COLOR,
+    reducedMotion: rawArgs.includes("--reduced-motion") || Boolean(env.CATHERD_REDUCED_MOTION),
+  };
+}
+
+/** A token's colour, or undefined when the terminal gets no colour. */
+export const paint = (ui: Ui, token: Token): string | undefined =>
+  ui.color ? PALETTES[ui.mode][token] : undefined;
+
+export { glyph, GLYPH_NAMES, type Glyph, type State } from "../glyphs.ts";
+
+/** Each state's colour token; the word travels with it. */
+export const STATE_TOKEN: Record<State, Token> = {
+  ok: "success",
+  warn: "warning",
+  fail: "error",
+  skip: "muted",
+};
+
+export type Mood = "good" | "working" | "waiting" | "failed";
+export const FACES: Record<Mood, string> = {
+  good: "=^.^=",
+  working: "=o.o=",
+  waiting: "=-.-=",
+  failed: "=x.x=",
+};
+
+/** The conductor, for the init welcome and empty states only (spec §9.3). ASCII already. */
+export function mascot(mood: Mood): [string, string, string] {
+  return [" /\\_/\\  .", `(${FACES[mood]})/`, ' (")(")'].map((l) => l.padEnd(9)) as [string, string, string];
+}
+
+/** Spec §9.3 motion: a braille spinner at 80 ms, shown after 500 ms and kept at least 3 s. */
+export const SPINNER = {
+  frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  plainFrames: ["|", "/", "-", "\\"],
+  still: ["⋯", "..."],
+  ms: 80,
+  showAfterMs: 500,
+  minShowMs: 3_000,
+} as const;
+
+/** Spec §9.3: dialogs are 60, 88 or 116 columns, clamped to the terminal. */
+export const DIALOG_WIDTH = { medium: 60, large: 88, xlarge: 116 } as const;
+export type DialogSize = keyof typeof DIALOG_WIDTH;

package/src/entry/tui/views/app.tsx

@@ -0,0 +1,208 @@
+import { useTerminalDimensions } from "@opentui/react";
+import { type CommandId, formatKeys } from "../commands.ts";
+import { hereWord } from "../effects.ts";
+import { useApp, useDialogHandler } from "../providers/app.tsx";
+import { DataProvider, useData } from "../providers/data.tsx";
+import { reachableCommands, useCommandLayer, useKeybinds, useKeymap } from "../providers/keymap.tsx";
+import { useUi } from "../providers/theme.tsx";
+import { currentDraft, isArmed, isSaving, TABS, totalDirty } from "../state.ts";
+import type { Mood } from "../theme.ts";
+import { Footer, Header, Tabs } from "../widgets/chrome.tsx";
+import { plural } from "../text.ts";
+import { Rule } from "../widgets/line.tsx";
+import { Spinner, useDelayedPresence } from "../widgets/spinner.tsx";
+import { ToastHost } from "../widgets/toast.tsx";
+import { Behind, DialogHost } from "./dialogs.tsx";
+import { playStory, STORIES } from "../stories.ts";
+import { openNewProfile, openProfileList, useProfileDialogs } from "./profile-actions.ts";
+import { ProfilesView } from "./profiles.tsx";
+import { RunsView } from "./runs.tsx";
+import { StatusView } from "./status.tsx";
+
+/** Rows the chrome takes at any size: header, tabs, rule, rule, footer (spec §9.3: 19 of 24 rows left). */
+const CHROME_ROWS = 5;
+
+/** The palette's and help's rows, read from the commands a key could reach before the dialog opens. */
+function useCommandDialogs() {
+  const app = useApp();
+  const keymap = useKeymap();
+  const keys = useKeybinds();
+  const ui = useUi();
+  const open = (kind: "palette" | "help") => {
+    const entries = reachableCommands(keymap).filter((c) =>
+      kind === "palette" ? c.palette : keys[c.id].length > 0 && !c.id.startsWith("dialog."),
+    );
+    app.dispatch({
+      type: "open",
+      dialog: {
+        kind: "select",
+        purpose: { type: kind },
+        title: kind === "palette" ? "Commands" : "Keyboard shortcuts",
+        empty: "no commands",
+        suggested: kind === "palette" ? entries.filter((c) => c.suggested).map((c) => c.id) : [],
+        options: entries.map((c) => ({
+          value: c.id,
+          title: c.title,
+          group: c.group,
+          detail: formatKeys(keys[c.id as CommandId], ui.plain),
+          ...(kind === "palette" && c.cli ? { cli: c.cli } : {}),
+        })),
+      },
+    });
+  };
+  const run = (_p: unknown, id: string) => {
+    app.dispatch({ type: "close" });
+    keymap.dispatchCommand(id);
+  };
+  useDialogHandler("palette", run);
+  useDialogHandler("help", run);
+  return open;
+}
+
+/** The storybook's picker (CATHERD_STORY=1): a story plays from a clean state. */
+function useStories(on: boolean) {
+  const app = useApp();
+  const keymap = useKeymap();
+  useDialogHandler("stories", (_p, name) => {
+    app.dispatch({ type: "close" });
+    const story = STORIES.find((s) => s.name === name);
+    if (story) void playStory(story, app, keymap, () => new Promise((r) => app.clock.setTimeout(r, 50)));
+  });
+  return on
+    ? () =>
+        app.dispatch({
+          type: "open",
+          dialog: {
+            kind: "select",
+            purpose: { type: "stories" },
+            title: "Stories",
+            empty: "no stories",
+            options: STORIES.map((s) => ({ value: s.name, title: s.title, detail: s.name })),
+          },
+        })
+    : null;
+}
+
+function Screen(props: { story: boolean }) {
+  const app = useApp();
+  const data = useData();
+  const dims = useTerminalDimensions();
+  const openCommands = useCommandDialogs();
+  const openStories = useStories(props.story);
+  useProfileDialogs();
+  const { state } = app;
+  const dirty = totalDirty(state);
+  const quit = () => {
+    const dirty = totalDirty(app.getState());
+    if (dirty === 0) return app.exit(0);
+    app.dispatch({
+      type: "open",
+      dialog: {
+        kind: "confirm",
+        purpose: { type: "quit" },
+        title: "Quit with unsaved changes?",
+        message: [`${plural(dirty, "unsaved change")} will be lost.`],
+        yes: "Discard and quit",
+        no: "Keep editing",
+        destructive: true,
+      },
+    });
+  };
+  useDialogHandler("quit", () => app.exit(0));
+  const go = (by: number) => {
+    const tab = app.getState().tab;
+    app.dispatch({
+      type: "tab",
+      tab: TABS[(TABS.indexOf(tab) + by + TABS.length) % TABS.length] ?? "status",
+    });
+  };
+  useCommandLayer("global", {
+    // spec §9.2 ctrl+c: close a dialog, else clear a text input, else quit when clean; when dirty a second
+    // press within 1.5 s discards and exits 130
+    "app.interrupt": () => {
+      const state = app.getState();
+      const dirty = totalDirty(state);
+      // a save that is writing is never cut off: nothing closes or quits until it settles
+      if (isSaving(state)) return app.toast({ variant: "info", message: "saving… wait for it to finish" });
+      if (state.dialogs.length) return app.dispatch({ type: "close" });
+      if (app.back("input")) return;
+      if (dirty === 0) return app.exit(0);
+      const now = app.clock.now();
+      if (isArmed(state, "interrupt", "app", now)) return app.exit(130);
+      app.dispatch({ type: "arm", what: "interrupt", target: "app", at: now });
+      app.toast({
+        variant: "warning",
+        message: `${plural(dirty, "unsaved change")}: ctrl+c again to discard and quit`,
+      });
+    },
+    // esc backs out one level and never quits; an armed double press is a level of its own
+    "app.back": () => {
+      const state = app.getState();
+      const a = state.armed;
+      if (a) app.dispatch({ type: "disarm" });
+      if (a && isArmed(state, a.what, a.target, app.clock.now())) return;
+      if (state.dialogs.length) return app.dispatch({ type: "close" });
+      app.back();
+    },
+  });
+  useCommandLayer("app", {
+    "app.palette": () => openCommands("palette"),
+    "app.help": () => openCommands("help"),
+    "app.quit": quit,
+    "tab.status": () => app.dispatch({ type: "tab", tab: "status" }),
+    "tab.profiles": () => app.dispatch({ type: "tab", tab: "profiles" }),
+    "tab.runs": () => app.dispatch({ type: "tab", tab: "runs" }),
+    "tab.next": () => go(1),
+    "tab.prev": () => go(-1),
+    "profile.new": () => openNewProfile(app),
+    "profile.list": () => openProfileList(app, data),
+    ...(openStories ? { "app.stories": openStories } : {}),
+  });
+  const checking = useDelayedPresence(data.checking);
+  const live = (data.runs.value?.rows ?? []).some((r) => r.live > 0);
+  const mood: Mood = data.report && !data.report.ready ? "failed" : live ? "working" : "good";
+  const draft = currentDraft(state);
+  const shown = draft?.name ?? data.profiles.value?.here ?? null;
+  const height = Math.max(1, dims.height - CHROME_ROWS);
+  const w = dims.width;
+  return (
+    <box flexDirection="column" width={w} height={dims.height}>
+      <box flexDirection="row" width={w} height={1}>
+        <Header
+          version={app.effects.version}
+          profile={shown}
+          active={shown !== null && shown === data.profiles.value?.here}
+          label={hereWord(data.profiles.value ?? { repo: null })}
+          dirty={dirty}
+          mood={mood}
+          width={checking ? w - 18 : w}
+        />
+        {checking ? (
+          <box width={18}>
+            <Spinner label="checking setup" />
+          </box>
+        ) : null}
+      </box>
+      <Tabs tab={state.tab} width={w} />
+      <Rule width={w} />
+      <Behind width={w} height={height}>
+        {state.tab === "status" ? <StatusView width={w} height={height} /> : null}
+        {state.tab === "profiles" ? <ProfilesView width={w} height={height} /> : null}
+        {state.tab === "runs" ? <RunsView width={w} height={height} /> : null}
+      </Behind>
+      <Rule width={w} />
+      <Footer width={w} />
+      <DialogHost />
+      <ToastHost />
+    </box>
+  );
+}
+
+/** Spec §9: one app, three tabs, dialogs and toasts over them. Must sit inside `Providers`. */
+export function App(props: { story?: boolean }) {
+  return (
+    <DataProvider>
+      <Screen story={props.story === true} />
+    </DataProvider>
+  );
+}

package/src/entry/tui/views/dialogs.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import { useApp } from "../providers/app.tsx";
+import { useUi } from "../providers/theme.tsx";
+import { DialogConfirm } from "../widgets/dialog-confirm.tsx";
+import { DialogPrompt } from "../widgets/dialog-prompt.tsx";
+import { DialogSelect } from "../widgets/dialog-select.tsx";
+import { SaveDialog } from "./save-dialog.tsx";
+
+/** Draws the top dialog of the stack; a new dialog remounts, so its cursor and filter start fresh. */
+export function DialogHost() {
+  const { state } = useApp();
+  const top = state.dialogs.at(-1);
+  if (!top) return null;
+  const key = `${state.dialogs.length}:${top.purpose.type}`;
+  switch (top.kind) {
+    case "select":
+      return <DialogSelect key={key} dialog={top} />;
+    case "confirm":
+      return <DialogConfirm key={key} dialog={top} />;
+    case "prompt":
+      return <DialogPrompt key={key} dialog={top} />;
+    case "save":
+      return <SaveDialog key={key} dialog={top} />;
+  }
+}
+
+/**
+ * What an open dialog is drawn over. Without colour nothing can paint the panel opaque (a space
+ * with no background shows what is beneath), so there the dialog replaces these lines instead.
+ */
+export function Behind(props: { width: number; height: number; children: ReactNode }) {
+  const { state } = useApp();
+  const ui = useUi();
+  return (
+    <box width={props.width} height={props.height}>
+      <box width={props.width} height={props.height} visible={!(state.dialogs.length > 0 && !ui.color)}>
+        {props.children}
+      </box>
+    </box>
+  );
+}