@d3lm/pr-stats 0.2.13 → 0.2.15

package/README.md

@@ -7,7 +7,7 @@ An interactive terminal UI for GitHub PR statistics, built with [OpenTUI](https:
 ## Requirements
 
 - Node 26.4+ or Bun 1.3+. The TUI renders through native FFI. Node gates that behind `--experimental-ffi`, and the launcher re-executes itself with the flag, so a plain `pr-stats` works on both runtimes.
-- Either an authenticated gh CLI (`gh auth login`) or a GitHub access token via `--token`, `GITHUB_TOKEN`, or `GH_TOKEN`. With a token, the tool calls the GitHub API directly and does not need the gh CLI. Private repositories need the `repo` scope.
+- Either an authenticated gh CLI (`gh auth login`) or a GitHub access token via `--token`, `GITHUB_TOKEN`, or `GH_TOKEN`. With a token, the tool calls the GitHub API directly and does not need the gh CLI. See [Tokens](#tokens) for the access a token needs.
 
 ## Install
 
@@ -70,6 +70,21 @@ pr-stats --work-hours 9-17 --target 1d
 pr-stats --review-types approve,request-changes
 ```
 
+## Tokens
+
+The `--token` flag and the `GITHUB_TOKEN` and `GH_TOKEN` environment variables switch the tool from the gh CLI to direct GitHub API calls. The PR list comes from the GitHub search API, which silently leaves out every repository the token cannot see, so a token with too little access shows an empty view instead of an error.
+
+A classic token needs the `repo` scope, or `public_repo` when every repository is public.
+
+A fine-grained token needs more care, because it only covers one resource owner and only the repositories you select for it.
+
+- Pick the organization as the resource owner when the PRs live in an organization's repositories. A token owned by your user account never sees them.
+- Grant access to all repositories or select the ones you care about. The public repositories option hides every private one.
+- Grant read access to `Metadata`, `Pull requests`, and `Contents`. Searching pull requests in private repositories needs `Contents` on top of `Pull requests`, even though GitHub's permission tables do not mention it.
+- Ask an organization owner to approve the token when the organization requires approval for fine-grained tokens. Until then, the token sees nothing in that organization.
+
+To check a token, run `pr-stats --token <token> --repo owner/name` against a repository you expect to see. Naming the repository makes the search fail with a `422 Validation Failed` error when the token cannot see it, where a search without `--repo` would just return nothing.
+
 ## JSON export
 
 The `--json` flag prints the full report to stdout instead of starting the TUI. Every other flag applies the same way, and progress renders on stderr, so a piped stdout stays pure JSON.
@@ -88,6 +103,36 @@ The cache lives in `~/Library/Caches/pr-stats` on macOS and in `$XDG_CACHE_HOME/
 
 The options modal saves the current options to the cache directory with the `s` key. Later runs start from the saved options wherever no flag was given, and flags always take precedence.
 
+## Auto Reload
+
+The `r` key reloads the data by hand, and `R` refetches everything past the cache. The TUI can also keep itself fresh while it stays open. The Auto reload row in the settings dialog turns background reloads on, and the Reload interval row below it sets how long the TUI waits after one load finishes before the next one starts, as a value in seconds, minutes, or hours like `30s`, `10m`, or `2h`. The header shows the interval next to the refresh time while it is on. Both settings persist in `settings.json` in the cache directory.
+
+```json
+{
+  "autoReload": true,
+  "reloadInterval": "10m"
+}
+```
+
+## Notifications
+
+The Desktop notifications row in the settings dialog makes the TUI send a desktop notification whenever a load finds a PR newly awaiting your review or a review re-requested from you after you already reviewed the PR. Every load diffs its review requests against the load before it, so the first load of a session only records what is already waiting and never notifies about it. Manual reloads count as well, but the feature pairs naturally with auto reload, which lets the TUI watch your review queue from a spare terminal. The setting persists in `settings.json` in the cache directory.
+
+```json
+{
+  "notifications": true,
+  "notifyChannel": "auto"
+}
+```
+
+Notifications go through the terminal itself when it supports a notification escape sequence, which covers iTerm2, Kitty, Ghostty, WezTerm, and most VTE-based terminals like GNOME Terminal. The terminal posts the notification under its own notification permission and the sequence travels through SSH, so this path needs no setup beyond what the terminal asks for. Some terminals only show the banner while their window is unfocused. Terminals without such support get the platform's own command instead, `osascript` on macOS and `notify-send` on Linux. A notification that fails to send reports in the footer, for example when `notify-send` is missing on a Linux machine.
+
+The "Notification channel" row picks the path, and the choice persists as `notifyChannel` with the values `auto`, `terminal`, `command`, and `bell`. On `auto` the TUI tries the terminal first and falls back to the platform command, `terminal` and `command` force one of those paths, and `bell` rings the terminal bell instead of posting any text. The dialog shows the `command` value as the command's name on this platform. Forcing the command pays off inside editor terminals like the one in VS Code, which render the terminal path as a small in-editor toast instead of a system notification. The bell reaches every terminal, including the ones that swallow notifications, and each terminal turns it into its own signal, a sound, a flashing screen, a bell icon on the tab, or a badge on the dock icon. The "Send test notification" row below the channel names the channel the next send takes and sends a sample notification, so you can check that your desktop displays it before relying on it.
+
+Two terminals accept the notification sequence without showing anything, and the test row warns about both. iTerm2 drops it until the profile has "Notification Center Alerts" turned on under Settings → Profiles → Terminal, which is off by default. Behind the "Filter Alerts…" button next to it, "Send escape sequence-generated alerts" has to stay on as well, and macOS asks for iTerm2's notification permission on the first send. iTerm2 prefixes the banner with the session name unless its advanced setting "Omit session identifier from notifications" is on. Apple Terminal never implemented the sequence at all, so `auto` skips the terminal there and goes straight to the platform command.
+
+The macOS command posts through the built-in Script Editor, and since macOS 15 those notifications stay invisible until Script Editor holds notification permission, without any prompt appearing. To grant it once, open the Script Editor app, run the one-line script `display notification "test"`, and allow the prompt that appears. Script Editor then shows up under Notifications in the System Settings like any other app.
+
 ## Theming
 
 The TUI ships five built-in themes, the warm amber default plus green, blue, purple, and yellow variants. The Theme row in the settings dialog cycles through them, and the Edit colors row below it edits individual colors, which creates a custom theme that joins the cycle as a sixth entry. Everything persists in a `theme` object in `settings.json` in the cache directory, which you can also edit by hand.

package/dist/tui-app.mjs

@@ -135,8 +135,8 @@ import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 
 // src/tui/App.tsx
-import { useKeyboard, useRenderer as useRenderer2, useTerminalDimensions as useTerminalDimensions3 } from "@opentui/react";
-import { useEffect as useEffect6, useMemo as useMemo2, useReducer, useRef as useRef5, useState as useState4 } from "react";
+import { useKeyboard, useRenderer as useRenderer3, useTerminalDimensions as useTerminalDimensions3 } from "@opentui/react";
+import { useEffect as useEffect7, useMemo as useMemo2, useReducer, useRef as useRef6, useState as useState4 } from "react";
 
 // src/settings.ts
 import { readFileSync as readFileSync2, rmSync as rmSync2 } from "node:fs";
@@ -279,10 +279,36 @@ function percentile(sorted, percent) {
 }
 
 // src/settings.ts
+var NOTIFY_CHANNELS = ["auto", "terminal", "command", "bell"];
+var DEFAULT_RELOAD_INTERVAL = "10m";
+var MAX_RELOAD_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function reloadIntervalMs(input) {
+  const match = /^(\d+)([smh])$/.exec(input);
+  if (match === null) {
+    return null;
+  }
+  const ms = Number(match[1]) * (match[2] === "h" ? 36e5 : match[2] === "m" ? 6e4 : 1e3);
+  return ms >= 1e3 && ms <= MAX_RELOAD_INTERVAL_MS ? ms : null;
+}
+function parseReloadInterval(input) {
+  const ms = reloadIntervalMs(input);
+  if (ms === null) {
+    throw new CliError(`invalid reload interval "${input}", use a value from 1s to 24h like 30s, 10m, or 2h`);
+  }
+  return ms;
+}
 function settingsFile() {
   return join2(cacheDir(), "settings.json");
 }
 var current = {};
+function writeCurrent() {
+  if (!cacheEnabled()) {
+    return false;
+  }
+  writeFileAtomic(settingsFile(), `${JSON.stringify(current, null, 2)}
+`);
+  return true;
+}
 function loadSettings() {
   current = {};
   if (!cacheEnabled()) {
@@ -310,26 +336,46 @@ function loadSettings() {
   if (settings.copyLinks !== void 0 && typeof settings.copyLinks !== "boolean") {
     throw new CliError(`"copyLinks" in ${settingsFile()} must be true or false`);
   }
+  if (settings.autoReload !== void 0 && typeof settings.autoReload !== "boolean") {
+    throw new CliError(`"autoReload" in ${settingsFile()} must be true or false`);
+  }
+  if (settings.reloadInterval !== void 0 && (typeof settings.reloadInterval !== "string" || reloadIntervalMs(settings.reloadInterval) === null)) {
+    throw new CliError(
+      `"reloadInterval" in ${settingsFile()} must be an interval from 1s to 24h like "30s", "10m", or "2h"`
+    );
+  }
+  if (settings.notifications !== void 0 && typeof settings.notifications !== "boolean") {
+    throw new CliError(`"notifications" in ${settingsFile()} must be true or false`);
+  }
+  if (settings.notifyChannel !== void 0 && !NOTIFY_CHANNELS.includes(settings.notifyChannel)) {
+    throw new CliError(`"notifyChannel" in ${settingsFile()} must be "auto", "terminal", "command", or "bell"`);
+  }
   current = settings;
   return current;
 }
 function saveNoCache(on) {
   current = { ...current, noCache: on };
-  if (!cacheEnabled()) {
-    return false;
-  }
-  writeFileAtomic(settingsFile(), `${JSON.stringify(current, null, 2)}
-`);
-  return true;
+  return writeCurrent();
 }
 function saveCopyLinks(on) {
   current = { ...current, copyLinks: on };
-  if (!cacheEnabled()) {
-    return false;
-  }
-  writeFileAtomic(settingsFile(), `${JSON.stringify(current, null, 2)}
-`);
-  return true;
+  return writeCurrent();
+}
+function saveAutoReload(on) {
+  current = { ...current, autoReload: on };
+  return writeCurrent();
+}
+function saveReloadInterval(value2) {
+  current = { ...current, reloadInterval: value2 };
+  return writeCurrent();
+}
+function saveNotifications(on) {
+  current = { ...current, notifications: on };
+  return writeCurrent();
+}
+function saveNotifyChannel(channel) {
+  current = { ...current, notifyChannel: channel };
+  return writeCurrent();
 }
 function saveTheme(value2) {
   current = { ...current };
@@ -338,12 +384,7 @@ function saveTheme(value2) {
   } else {
     current.theme = value2;
   }
-  if (!cacheEnabled()) {
-    return false;
-  }
-  writeFileAtomic(settingsFile(), `${JSON.stringify(current, null, 2)}
-`);
-  return true;
+  return writeCurrent();
 }
 function resetSettings() {
   if (!cacheEnabled()) {
@@ -598,7 +639,7 @@ function hintsFor(modal, editing, tab, authoredTab, views, copyLinks2) {
     return editing ? "enter apply \xB7 esc cancel" : "\u2191/\u2193 select \xB7 enter edit \xB7 \u2190/\u2192 toggle \xB7 s save \xB7 esc close \xB7 q quit";
   }
   if (modal === "settings") {
-    return "\u2191/\u2193 select \xB7 enter apply \xB7 \u2190/\u2192 toggle \xB7 esc close \xB7 q quit";
+    return editing ? "enter apply \xB7 esc cancel" : "\u2191/\u2193 select \xB7 enter apply \xB7 \u2190/\u2192 toggle \xB7 esc close \xB7 q quit";
   }
   if (modal === "theme") {
     return editing ? "enter apply \xB7 esc cancel" : "\u2191/\u2193 select \xB7 enter edit hex \xB7 esc back \xB7 q quit";
@@ -1684,7 +1725,8 @@ function Header({
   options,
   raw,
   error,
-  spinning
+  spinning,
+  reloadEvery
 }) {
   const context = [
     raw ? `@${raw.user}` : options.user !== "" ? `@${options.user}` : "@...",
@@ -1692,7 +1734,7 @@ function Header({
     raw && raw.repos.length > 0 ? raw.repos.join(", ") : options.repos !== "" ? options.repos : "all repos",
     timeModeLabel(options)
   ].join(" \xB7 ");
-  const rightStatus = raw ? error !== null ? "reload failed \xB7 press r to retry" : `refreshed ${raw.fetchedAt.toLocaleTimeString()}` : "";
+  const rightStatus = raw ? error !== null ? "reload failed \xB7 press r to retry" : `refreshed ${raw.fetchedAt.toLocaleTimeString()}${reloadEvery === null ? "" : ` \xB7 every ${reloadEvery}`}` : "";
   return /* @__PURE__ */ jsxs2("box", { flexDirection: "row", height: 1, paddingLeft: 1, paddingRight: 1, justifyContent: "space-between", children: [
     /* @__PURE__ */ jsxs2("text", { wrapMode: "none", children: [
       /* @__PURE__ */ jsx3("b", { fg: theme.accent, children: "pr-stats" }),
@@ -3005,6 +3047,31 @@ function ModalRow({ label, isSelected, children }) {
     }
   );
 }
+function ModalInput({
+  width,
+  value: value2,
+  onDraft,
+  onSubmit
+}) {
+  return /* @__PURE__ */ jsx10(
+    "input",
+    {
+      width,
+      value: value2,
+      focused: true,
+      onInput: (next) => {
+        onDraft(String(next));
+      },
+      onSubmit: () => {
+        onSubmit();
+      },
+      backgroundColor: theme.inputBg,
+      focusedBackgroundColor: theme.inputFocusedBg,
+      textColor: theme.text,
+      cursorColor: theme.accent
+    }
+  );
+}
 
 // src/tui/components/OptionsModal.tsx
 import { jsx as jsx11, jsxs as jsxs10 } from "@opentui/react/jsx-runtime";
@@ -3118,24 +3185,7 @@ function FieldRow({
       )
     ] });
   }
-  return /* @__PURE__ */ jsx11(ModalRow, { label: field.label, isSelected, children: isEditing ? /* @__PURE__ */ jsx11(
-    "input",
-    {
-      width: 32,
-      value: String(options[field.key]),
-      focused: true,
-      onInput: (next) => {
-        onDraft(String(next));
-      },
-      onSubmit: () => {
-        onSubmit();
-      },
-      backgroundColor: theme.inputBg,
-      focusedBackgroundColor: theme.inputFocusedBg,
-      textColor: theme.text,
-      cursorColor: theme.accent
-    }
-  ) : isSelected && field.kind === "toggle" ? /* @__PURE__ */ jsxs10("text", { wrapMode: "none", children: [
+  return /* @__PURE__ */ jsx11(ModalRow, { label: field.label, isSelected, children: isEditing ? /* @__PURE__ */ jsx11(ModalInput, { width: 32, value: String(options[field.key]), onDraft, onSubmit }) : isSelected && field.kind === "toggle" ? /* @__PURE__ */ jsxs10("text", { wrapMode: "none", children: [
     /* @__PURE__ */ jsx11("span", { fg: theme.muted, children: "\u2039 " }),
     /* @__PURE__ */ jsx11("b", { fg: theme.text, children: value2.text }),
     /* @__PURE__ */ jsx11("span", { fg: theme.muted, children: " \u203A" })
@@ -3175,6 +3225,7 @@ function Checklist({
 }
 
 // src/tui/components/SettingsModal.tsx
+import { useRenderer as useRenderer2 } from "@opentui/react";
 import { homedir as homedir2 } from "node:os";
 
 // src/tui/data/export.ts
@@ -4022,6 +4073,36 @@ var SETTINGS = [
     label: "Clear cache",
     hint: "deletes the cached PR data at this path, so the next reload refetches everything"
   },
+  {
+    key: "autoReload",
+    section: "Reload",
+    label: "Auto reload",
+    hint: "reloads the data in the background on the interval below, so the charts stay fresh while the TUI keeps running"
+  },
+  {
+    key: "reloadInterval",
+    section: "Reload",
+    label: "Reload interval",
+    hint: "time between the background reloads while auto reload is on, like 30s, 10m, or 2h \xB7 enter edits the value"
+  },
+  {
+    key: "notifications",
+    section: "Notifications",
+    label: "Desktop notifications",
+    hint: "notifies you when a load finds a PR newly awaiting your review or a review re-requested from you"
+  },
+  {
+    key: "notifyChannel",
+    section: "Notifications",
+    label: "Notification channel",
+    hint: "auto tries the terminal, then the platform command \xB7 the others force one path \xB7 bell rings the terminal bell"
+  },
+  {
+    key: "testNotification",
+    section: "Notifications",
+    label: "Send test notification",
+    hint: "sends a sample notification through the channel shown, so you can check that your desktop displays it"
+  },
   {
     key: "copyLinks",
     section: "Links",
@@ -4082,9 +4163,140 @@ var CACHE_MESSAGES = {
   resetDisabled: { text: "the cache is disabled for this session \xB7 nothing to reset" },
   exported: { text: "stats exported \xB7 the same report prints to stdout with the --json flag" },
   exportFailed: { text: "the export failed \xB7 the file could not be written", warn: true },
-  exportNoData: { text: "no loaded stats to export yet \xB7 export again once the load finishes", warn: true }
+  exportNoData: { text: "no loaded stats to export yet \xB7 export again once the load finishes", warn: true },
+  notified: { text: "test notification sent \xB7 a failure to deliver it reports in the footer" }
 };
 
+// src/tui/utils/notify.ts
+import { spawn } from "node:child_process";
+function notificationBoundary(renderer2) {
+  const raw = renderer2;
+  return {
+    get capabilities() {
+      return renderer2.capabilities;
+    },
+    triggerNotification: (message, title) => renderer2.triggerNotification(message, title),
+    writeOut: (data) => {
+      if (typeof raw.writeOut === "function") {
+        raw.writeOut(data);
+      } else {
+        process.stdout.write(data);
+      }
+    }
+  };
+}
+var BELL = "\x07";
+function terminalQuirk(renderer2) {
+  const name = renderer2.capabilities?.terminal.name ?? "";
+  if (/iterm/i.test(name)) {
+    return "iterm";
+  }
+  if (/apple_terminal|terminal\.app/i.test(name)) {
+    return "apple-terminal";
+  }
+  return null;
+}
+function createNotifier(renderer2, channel) {
+  return (title, body, onError) => {
+    if (channel === "bell") {
+      renderer2.writeOut(BELL);
+      return;
+    }
+    const tryTerminal = channel === "terminal" || channel === "auto" && terminalQuirk(renderer2) !== "apple-terminal";
+    if (tryTerminal && renderer2.triggerNotification(body, title)) {
+      return;
+    }
+    if (channel === "terminal") {
+      onError("the terminal has no notification support, switch the channel to auto, the platform command, or bell");
+      return;
+    }
+    sendNotification(title, body, onError);
+  };
+}
+function notificationChannel(renderer2, channel) {
+  if (channel === "bell" || channel === "terminal") {
+    return channel;
+  }
+  if (channel === "auto" && renderer2.capabilities?.notifications === true && terminalQuirk(renderer2) !== "apple-terminal") {
+    return "terminal";
+  }
+  return notificationTool();
+}
+function notificationCaveat(renderer2, channel) {
+  if (channel === "command" || channel === "bell") {
+    return null;
+  }
+  switch (terminalQuirk(renderer2)) {
+    case "iterm": {
+      return "iTerm2 shows these only once Notification Center Alerts is on under Settings \u203A Profiles \u203A Terminal";
+    }
+    case "apple-terminal": {
+      return channel === "auto" ? "Terminal.app ignores terminal notifications, so auto takes the platform command here" : "Terminal.app ignores terminal notifications \xB7 switch the channel to auto, command, or bell";
+    }
+    default: {
+      return null;
+    }
+  }
+}
+function notificationTool() {
+  switch (process.platform) {
+    case "darwin": {
+      return "osascript";
+    }
+    case "linux": {
+      return "notify-send";
+    }
+    default: {
+      return null;
+    }
+  }
+}
+function escapeMarkup(text) {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function notifyCommand(title, body) {
+  switch (process.platform) {
+    case "darwin": {
+      return {
+        command: "osascript",
+        args: [
+          "-e",
+          "on run argv",
+          "-e",
+          'display notification (item 2 of argv) with title (item 1 of argv) sound name "default"',
+          "-e",
+          "end run",
+          title,
+          body
+        ]
+      };
+    }
+    case "linux": {
+      return { command: "notify-send", args: ["--app-name=pr-stats", "--", title, escapeMarkup(body)] };
+    }
+    default: {
+      return null;
+    }
+  }
+}
+function sendNotification(title, body, onError) {
+  const spec = notifyCommand(title, body);
+  if (spec === null) {
+    onError("desktop notifications are not supported on this platform");
+    return;
+  }
+  const child = spawn(spec.command, spec.args, { stdio: "ignore", detached: true });
+  child.on("error", (error) => {
+    onError(`could not send the notification (${error.message})`);
+  });
+  child.on("exit", (code) => {
+    if (code !== null && code !== 0) {
+      onError(`could not send the notification (${spec.command} exited with ${code})`);
+    }
+  });
+  child.unref();
+}
+
 // src/tui/components/SettingsModal.tsx
 import { jsx as jsx12, jsxs as jsxs11 } from "@opentui/react/jsx-runtime";
 var SECTIONS2 = [];
@@ -4098,12 +4310,25 @@ for (const setting of SETTINGS) {
 }
 function SettingsModal({
   selected,
+  editing,
+  error,
   cacheAction,
   noCache: noCache2,
+  autoReload: autoReload2,
+  reloadInterval: reloadInterval2,
+  notifications: notifications2,
+  notifyChannel: notifyChannel2,
   copyLinks: copyLinks2,
-  preset
+  preset,
+  onDraft,
+  onSubmit
 }) {
   const message = cacheAction === null ? null : CACHE_MESSAGES[cacheAction];
+  const renderer2 = notificationBoundary(useRenderer2());
+  const channelValue = notifyChannel2 === "command" ? notificationTool() ?? "unsupported" : notifyChannel2;
+  const deliveryValue = notificationChannel(renderer2, notifyChannel2) ?? "unsupported";
+  const caveat = SETTINGS[selected].key === "testNotification" ? notificationCaveat(renderer2, notifyChannel2) : null;
+  const bottomLine = error !== null ? { text: error, fg: theme.error } : message !== null ? { text: message.text, fg: message.warn ? theme.warn : theme.muted } : caveat !== null ? { text: caveat, fg: theme.warn } : { text: SETTINGS[selected].hint, fg: theme.muted };
   return /* @__PURE__ */ jsxs11(ModalFrame, { title: "Settings", children: [
     SECTIONS2.map((section) => /* @__PURE__ */ jsxs11("box", { flexDirection: "column", marginBottom: 1, children: [
       /* @__PURE__ */ jsx12("text", { wrapMode: "none", fg: theme.accent, marginLeft: 2, children: section.title }),
@@ -4114,24 +4339,40 @@ function SettingsModal({
           {
             setting,
             isSelected,
+            isEditing: isSelected && editing,
             cacheAction,
             noCache: noCache2,
+            autoReload: autoReload2,
+            reloadInterval: reloadInterval2,
+            notifications: notifications2,
+            channelValue,
+            deliveryValue,
             copyLinks: copyLinks2,
-            preset
+            preset,
+            onDraft,
+            onSubmit
           }
         ) }, setting.key);
       })
     ] }, section.title)),
-    /* @__PURE__ */ jsx12("text", { wrapMode: "word", height: 2, fg: message?.warn ? theme.warn : theme.muted, marginLeft: 2, marginRight: 2, children: message?.text ?? SETTINGS[selected].hint })
+    /* @__PURE__ */ jsx12("text", { wrapMode: "word", height: 2, fg: bottomLine.fg, marginLeft: 2, marginRight: 2, children: bottomLine.text })
   ] });
 }
 function SettingValue({
   setting,
   isSelected,
+  isEditing,
   cacheAction,
   noCache: noCache2,
+  autoReload: autoReload2,
+  reloadInterval: reloadInterval2,
+  notifications: notifications2,
+  channelValue,
+  deliveryValue,
   copyLinks: copyLinks2,
-  preset
+  preset,
+  onDraft,
+  onSubmit
 }) {
   switch (setting.key) {
     case "noCache": {
@@ -4140,6 +4381,24 @@ function SettingValue({
     case "clearCache": {
       return /* @__PURE__ */ jsx12(PathValue, { path: cacheDir(), confirming: cacheAction === "confirm", isSelected });
     }
+    case "autoReload": {
+      return /* @__PURE__ */ jsx12(ToggleValue, { value: autoReload2 ? "yes" : "no", isSelected });
+    }
+    case "reloadInterval": {
+      if (isEditing) {
+        return /* @__PURE__ */ jsx12(ModalInput, { width: 16, value: reloadInterval2, onDraft, onSubmit });
+      }
+      return /* @__PURE__ */ jsx12(IntervalValue, { value: reloadInterval2, active: autoReload2, isSelected });
+    }
+    case "notifications": {
+      return /* @__PURE__ */ jsx12(ToggleValue, { value: notifications2 ? "yes" : "no", isSelected });
+    }
+    case "notifyChannel": {
+      return /* @__PURE__ */ jsx12(ToggleValue, { value: channelValue, isSelected });
+    }
+    case "testNotification": {
+      return /* @__PURE__ */ jsx12("text", { wrapMode: "none", fg: isSelected ? theme.text : theme.muted, children: deliveryValue });
+    }
     case "copyLinks": {
       return /* @__PURE__ */ jsx12(ToggleValue, { value: copyLinks2 ? "yes" : "no", isSelected });
     }
@@ -4170,6 +4429,15 @@ function ToggleValue({ value: value2, isSelected }) {
   }
   return /* @__PURE__ */ jsx12("text", { wrapMode: "none", fg: theme.muted, children: value2 });
 }
+function IntervalValue({ value: value2, active, isSelected }) {
+  if (!active) {
+    return /* @__PURE__ */ jsx12("text", { wrapMode: "none", fg: isSelected ? theme.muted : theme.dim, children: value2 });
+  }
+  if (isSelected) {
+    return /* @__PURE__ */ jsx12("text", { wrapMode: "none", children: /* @__PURE__ */ jsx12("b", { fg: theme.text, children: value2 }) });
+  }
+  return /* @__PURE__ */ jsx12("text", { wrapMode: "none", fg: theme.muted, children: value2 });
+}
 function PathValue({ path, confirming, isSelected }) {
   if (confirming) {
     return /* @__PURE__ */ jsx12("text", { wrapMode: "none", children: /* @__PURE__ */ jsx12("b", { fg: theme.warn, children: "enter to confirm" }) });
@@ -4217,24 +4485,7 @@ function ColorRow({
 }) {
   const value2 = themeColorText(color.key);
   const swatch = theme[color.key];
-  return /* @__PURE__ */ jsx13(ModalRow, { label: color.key, isSelected, children: isEditing ? /* @__PURE__ */ jsx13(
-    "input",
-    {
-      width: 36,
-      value: value2,
-      focused: true,
-      onInput: (next) => {
-        onDraft(String(next));
-      },
-      onSubmit: () => {
-        onSubmit();
-      },
-      backgroundColor: theme.inputBg,
-      focusedBackgroundColor: theme.inputFocusedBg,
-      textColor: theme.text,
-      cursorColor: theme.accent
-    }
-  ) : /* @__PURE__ */ jsxs12("text", { wrapMode: "none", children: [
+  return /* @__PURE__ */ jsx13(ModalRow, { label: color.key, isSelected, children: isEditing ? /* @__PURE__ */ jsx13(ModalInput, { width: 36, value: value2, onDraft, onSubmit }) : /* @__PURE__ */ jsxs12("text", { wrapMode: "none", children: [
     Array.isArray(swatch) ? /* @__PURE__ */ jsxs12(Fragment4, { children: [
       /* @__PURE__ */ jsx13("span", { fg: swatch[0], children: "\u2588" }),
       /* @__PURE__ */ jsx13("span", { fg: swatch[1], children: "\u2588" }),
@@ -4253,10 +4504,15 @@ function Modals({
   options,
   saved: saved2,
   noCache: noCache2,
+  autoReload: autoReload2,
+  reloadInterval: reloadInterval2,
+  notifications: notifications2,
+  notifyChannel: notifyChannel2,
   copyLinks: copyLinks2,
   themeState,
   onDraft,
   onSubmitField,
+  onSubmitReloadInterval,
   onSubmitThemeColor,
   onToggleReviewType,
   onToggleWorkDay
@@ -4282,10 +4538,18 @@ function Modals({
       SettingsModal,
       {
         selected: ui.selectedSetting,
+        editing: ui.editing,
+        error: ui.settingError,
         cacheAction: ui.cacheAction,
         noCache: noCache2,
+        autoReload: autoReload2,
+        reloadInterval: reloadInterval2,
+        notifications: notifications2,
+        notifyChannel: notifyChannel2,
         copyLinks: copyLinks2,
-        preset: themeState.preset
+        preset: themeState.preset,
+        onDraft,
+        onSubmit: onSubmitReloadInterval
       }
     );
   }
@@ -4306,12 +4570,31 @@ function Modals({
   return null;
 }
 
+// src/tui/hooks/useAutoReload.ts
+import { useEffect as useEffect4, useEffectEvent } from "react";
+function useAutoReload(intervalMs, loading, reload) {
+  const tick = useEffectEvent(() => {
+    reload();
+  });
+  useEffect4(() => {
+    if (intervalMs === null || loading) {
+      return void 0;
+    }
+    const timer = setTimeout(() => {
+      tick();
+    }, intervalMs);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [intervalMs, loading]);
+}
+
 // src/tui/hooks/useDeferredLoading.ts
-import { useEffect as useEffect4, useRef as useRef3, useState as useState2 } from "react";
+import { useEffect as useEffect5, useRef as useRef3, useState as useState2 } from "react";
 function useDeferredLoading(isLoading, { showDelay = 300, minDuration = 500 } = {}) {
   const [visible, setVisible] = useState2(isLoading && showDelay === 0);
   const shownAtRef = useRef3(null);
-  useEffect4(() => {
+  useEffect5(() => {
     if (isLoading) {
       const timer2 = setTimeout(() => {
         shownAtRef.current = Date.now();
@@ -4335,7 +4618,7 @@ function useDeferredLoading(isLoading, { showDelay = 300, minDuration = 500 } =
 }
 
 // src/tui/hooks/useLoader.ts
-import { useEffect as useEffect5, useRef as useRef4, useState as useState3 } from "react";
+import { useEffect as useEffect6, useRef as useRef4, useState as useState3 } from "react";
 function useLoader(options, noCache2, onLoaded) {
   const [startupSnapshot] = useState3(() => noCache2 ? null : loadSnapshot(options));
   const [raw, setRaw] = useState3(startupSnapshot);
@@ -4385,7 +4668,7 @@ function useLoader(options, noCache2, onLoaded) {
     void run(bypassCache || noCache2);
   };
   const startedRef = useRef4(false);
-  useEffect5(() => {
+  useEffect6(() => {
     disposedRef.current = false;
     if (!startedRef.current) {
       startedRef.current = true;
@@ -4406,6 +4689,85 @@ function useLoader(options, noCache2, onLoaded) {
   };
 }
 
+// src/tui/hooks/useReviewNotifications.ts
+import { useRef as useRef5 } from "react";
+
+// src/tui/data/notifications.ts
+function diffReviewRequests(previous, results) {
+  const baseline = /* @__PURE__ */ new Map();
+  const reviewedKeys = /* @__PURE__ */ new Set();
+  const pending = [];
+  for (const result of results) {
+    const key = `${result.pr.repo}#${result.pr.number}`;
+    if (result.kind === "reviewed") {
+      reviewedKeys.add(key);
+    } else if (result.kind === "pending" && result.pr.state === "open") {
+      const requestedAt = result.requestedAt.getTime();
+      baseline.set(key, requestedAt);
+      pending.push({ key, pr: result.pr, requestedAt });
+    }
+  }
+  if (previous === null) {
+    return { baseline, newRequests: [], reRequests: [] };
+  }
+  const newRequests = [];
+  const reRequests = [];
+  for (const { key, pr, requestedAt } of pending) {
+    const before = previous.get(key);
+    if (before !== void 0 && before >= requestedAt) {
+      continue;
+    }
+    (reviewedKeys.has(key) ? reRequests : newRequests).push(pr);
+  }
+  return { baseline, newRequests, reRequests };
+}
+var MAX_LISTED = 3;
+var TEST_NOTIFICATION = {
+  title: "pr-stats",
+  body: "Desktop notifications are working. New review requests show up like this."
+};
+function describeReviewRequests(changes) {
+  const notifications2 = [];
+  if (changes.newRequests.length > 0) {
+    notifications2.push(describe(changes.newRequests, "Review requested on", "new PRs awaiting your review"));
+  }
+  if (changes.reRequests.length > 0) {
+    notifications2.push(describe(changes.reRequests, "Review re-requested on", "PRs came back for review"));
+  }
+  return notifications2;
+}
+function describe(prs, singleTitle, pluralTitle) {
+  if (prs.length === 1) {
+    const [pr] = prs;
+    return { title: `${singleTitle} ${refOf(pr)}`, body: pr.title };
+  }
+  const lines = prs.slice(0, MAX_LISTED).map((pr) => `${refOf(pr)} ${pr.title}`);
+  const rest = prs.length - lines.length;
+  if (rest > 0) {
+    lines.push(`and ${rest} more`);
+  }
+  return { title: `${prs.length} ${pluralTitle}`, body: lines.join("\n") };
+}
+function refOf(pr) {
+  return `${pr.repo}#${pr.number}`;
+}
+
+// src/tui/hooks/useReviewNotifications.ts
+function useReviewNotifications(enabled2, notify, onError) {
+  const baselineRef = useRef5(null);
+  return (key, results) => {
+    const previous = baselineRef.current?.key === key ? baselineRef.current.baseline : null;
+    const changes = diffReviewRequests(previous, results);
+    baselineRef.current = { key, baseline: changes.baseline };
+    if (!enabled2) {
+      return;
+    }
+    for (const notification of describeReviewRequests(changes)) {
+      notify(notification.title, notification.body, onError);
+    }
+  };
+}
+
 // src/tui/hooks/useViewModel.ts
 import { useMemo } from "react";
 
@@ -6081,6 +6443,43 @@ function handleSettingsModalKey(key, context) {
           }
           break;
         }
+        case "autoReload": {
+          const next = !context.autoReload;
+          context.setAutoReload(next);
+          context.dispatchUi({ type: "cacheActionReported", action: saveAutoReload(next) ? "saved" : "notSaved" });
+          break;
+        }
+        case "reloadInterval": {
+          if (key.name !== "return") {
+            break;
+          }
+          context.beginEdit(context.reloadInterval);
+          break;
+        }
+        case "notifications": {
+          const next = !context.notifications;
+          context.setNotifications(next);
+          context.dispatchUi({ type: "cacheActionReported", action: saveNotifications(next) ? "saved" : "notSaved" });
+          break;
+        }
+        case "notifyChannel": {
+          const index = NOTIFY_CHANNELS.indexOf(context.notifyChannel);
+          const step = key.name === "left" ? -1 : 1;
+          const next = NOTIFY_CHANNELS[(index + step + NOTIFY_CHANNELS.length) % NOTIFY_CHANNELS.length];
+          context.setNotifyChannel(next);
+          context.dispatchUi({ type: "cacheActionReported", action: saveNotifyChannel(next) ? "saved" : "notSaved" });
+          break;
+        }
+        case "testNotification": {
+          if (key.name !== "return") {
+            break;
+          }
+          context.notify(TEST_NOTIFICATION.title, TEST_NOTIFICATION.body, (message) => {
+            context.dispatchUi({ type: "openErrorReported", message });
+          });
+          context.dispatchUi({ type: "cacheActionReported", action: "notified" });
+          break;
+        }
         case "copyLinks": {
           const next = !context.copyLinks;
           context.setCopyLinks(next);
@@ -6355,6 +6754,7 @@ var initialUiState = {
   selectedSetting: 0,
   selectedThemeColor: 0,
   fieldError: null,
+  settingError: null,
   themeColorError: null,
   cacheAction: null,
   openError: null,
@@ -6381,7 +6781,14 @@ function uiReducer(state, action) {
       return { ...state, successNotice: null };
     }
     case "modalOpened": {
-      return { ...state, modal: action.modal, fieldError: null, themeColorError: null, cacheAction: null };
+      return {
+        ...state,
+        modal: action.modal,
+        fieldError: null,
+        settingError: null,
+        themeColorError: null,
+        cacheAction: null
+      };
     }
     case "optionsModalClosed": {
       return { ...state, modal: null, fieldError: null };
@@ -6390,7 +6797,7 @@ function uiReducer(state, action) {
       if (state.cacheAction === "confirm" || state.cacheAction === "resetConfirm") {
         return { ...state, cacheAction: null };
       }
-      return { ...state, modal: null, cacheAction: null };
+      return { ...state, modal: null, settingError: null, cacheAction: null };
     }
     case "themeModalClosed": {
       return { ...state, modal: "settings", themeColorError: null, cacheAction: null };
@@ -6402,6 +6809,7 @@ function uiReducer(state, action) {
       return {
         ...state,
         selectedSetting: cycled2(state.selectedSetting, action.delta, SETTINGS.length),
+        settingError: null,
         cacheAction: null
       };
     }
@@ -6414,10 +6822,10 @@ function uiReducer(state, action) {
       };
     }
     case "editStarted": {
-      return { ...state, editing: true, fieldError: null, themeColorError: null };
+      return { ...state, editing: true, fieldError: null, settingError: null, themeColorError: null };
     }
     case "editCancelled": {
-      return { ...state, editing: false, fieldError: null, themeColorError: null };
+      return { ...state, editing: false, fieldError: null, settingError: null, themeColorError: null };
     }
     case "fieldCommitted": {
       return { ...state, editing: false, fieldError: null };
@@ -6431,6 +6839,12 @@ function uiReducer(state, action) {
       }
       return { ...state, fieldError: "the cache is disabled for this session \xB7 options not saved" };
     }
+    case "settingCommitted": {
+      return { ...state, editing: false, settingError: null, cacheAction: action.action };
+    }
+    case "settingErrorReported": {
+      return { ...state, settingError: action.message };
+    }
     case "themeColorCommitted": {
       return { ...state, editing: false, themeColorError: null, cacheAction: action.action };
     }
@@ -6445,7 +6859,7 @@ function uiReducer(state, action) {
 }
 
 // src/tui/utils/browser.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 function openCommand(url) {
   switch (process.platform) {
     case "darwin": {
@@ -6461,7 +6875,7 @@ function openCommand(url) {
 }
 function openInBrowser(url, onError) {
   const { command, args } = openCommand(url);
-  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  const child = spawn2(command, args, { stdio: "ignore", detached: true });
   child.on("error", (error) => {
     onError(`could not open the browser (${error.message})`);
   });
@@ -6508,14 +6922,19 @@ function App({
   initial: initial2,
   initialSaved = null,
   initialNoCache = false,
+  initialAutoReload = false,
+  initialReloadInterval = DEFAULT_RELOAD_INTERVAL,
+  initialNotifications = false,
+  initialNotifyChannel = "auto",
   initialCopyLinks = false,
   initialTheme = defaultThemeState(),
   openUrl = openInBrowser,
   copyUrl,
+  notify,
   onQuit
 }) {
   const { width } = useTerminalDimensions3();
-  const renderer2 = useRenderer2();
+  const renderer2 = useRenderer3();
   const defaultCopyUrl = useMemo2(() => createClipboardCopier(renderer2), [renderer2]);
   const copyLink = copyUrl ?? defaultCopyUrl;
   const [ui, dispatchUi] = useReducer(uiReducer, initialUiState);
@@ -6523,15 +6942,24 @@ function App({
   const [options, setOptions] = useState4(initial2);
   const [saved2, setSaved] = useState4(initialSaved);
   const [noCache2, setNoCache] = useState4(initialNoCache);
+  const [autoReload2, setAutoReload] = useState4(initialAutoReload);
+  const [reloadInterval2, setReloadInterval] = useState4(initialReloadInterval);
+  const [notifications2, setNotifications] = useState4(initialNotifications);
+  const [notifyChannel2, setNotifyChannel] = useState4(initialNotifyChannel);
   const [copyLinks2, setCopyLinks] = useState4(initialCopyLinks);
   const [themeState, setThemeState] = useState4(initialTheme);
+  const defaultNotify = useMemo2(
+    () => createNotifier(notificationBoundary(renderer2), notifyChannel2),
+    [renderer2, notifyChannel2]
+  );
+  const notifier = notify ?? defaultNotify;
   const copyRow = (row) => {
     copyLink(row.url, (message) => {
       dispatchUi({ type: "openErrorReported", message });
     });
     dispatchUi({ type: "copyReported", message: `copied ${row.ref} to the clipboard` });
   };
-  useEffect6(() => {
+  useEffect7(() => {
     if (ui.successNotice === null) {
       return void 0;
     }
@@ -6542,10 +6970,13 @@ function App({
       clearTimeout(timer);
     };
   }, [ui.successNotice]);
-  const reviewScrollRef = useRef5(null);
-  const sizeScrollRef = useRef5(null);
-  const commentScrollRef = useRef5(null);
-  const mergedScrollRef = useRef5(null);
+  const reviewScrollRef = useRef6(null);
+  const sizeScrollRef = useRef6(null);
+  const commentScrollRef = useRef6(null);
+  const mergedScrollRef = useRef6(null);
+  const notifyReviewChanges = useReviewNotifications(notifications2, notifier, (message) => {
+    dispatchUi({ type: "openErrorReported", message });
+  });
   const { raw, isSnapshot, loading, load, error, stale, reload } = useLoader(options, noCache2, (data) => {
     dispatchBrowse({
       type: "dataLoaded",
@@ -6558,10 +6989,12 @@ function App({
         merged: buildMergedRepoOptions(data)
       }
     });
+    notifyReviewChanges(fetchParamsKey(options), data.reviewResults);
   });
+  useAutoReload(autoReload2 ? reloadIntervalMs(reloadInterval2) : null, loading, reload);
   const views = useViewModel(raw, options, width, browse.scopes, browse.grouped, browse.expanded, themeState);
   const showLoad = useDeferredLoading(loading, isSnapshot ? { showDelay: 0 } : void 0);
-  const draftRef = useRef5("");
+  const draftRef = useRef6("");
   const commitField = () => {
     const field = FIELDS[ui.selectedField];
     const value2 = draftRef.current.trim();
@@ -6579,6 +7012,20 @@ function App({
       throw error2;
     }
   };
+  const commitReloadInterval = () => {
+    const value2 = draftRef.current.trim();
+    try {
+      parseReloadInterval(value2);
+      setReloadInterval(value2);
+      dispatchUi({ type: "settingCommitted", action: saveReloadInterval(value2) ? "saved" : "notSaved" });
+    } catch (error2) {
+      if (error2 instanceof CliError) {
+        dispatchUi({ type: "settingErrorReported", message: error2.message });
+        return;
+      }
+      throw error2;
+    }
+  };
   const commitThemeColor = () => {
     try {
       const next = withColorOverride(themeState, THEME_COLORS[ui.selectedThemeColor].key, draftRef.current.trim());
@@ -6594,10 +7041,17 @@ function App({
     }
   };
   useKeyboard((key) => {
+    if (ui.editing && key.name === "escape") {
+      renderer2.currentFocusedRenderable?.blur();
+    }
     handleAppKey(key, {
       ui,
       browse,
       noCache: noCache2,
+      autoReload: autoReload2,
+      reloadInterval: reloadInterval2,
+      notifications: notifications2,
+      notifyChannel: notifyChannel2,
       copyLinks: copyLinks2,
       themeState,
       options,
@@ -6608,11 +7062,15 @@ function App({
       setOptions,
       setSaved,
       setNoCache,
+      setAutoReload,
+      setNotifications,
+      setNotifyChannel,
       setCopyLinks,
       setThemeState,
       quit: onQuit,
       reload,
       openUrl,
+      notify: notifier,
       copyRow,
       beginEdit: (value2) => {
         draftRef.current = value2;
@@ -6626,7 +7084,16 @@ function App({
   });
   const capWarning = raw?.searchCapped ? "Warning, a search hit the 1000 result cap, so data may be incomplete. Narrow since or repos." : null;
   return /* @__PURE__ */ jsxs13("box", { flexDirection: "column", width: "100%", height: "100%", backgroundColor: theme.bg, children: [
-    /* @__PURE__ */ jsx15(Header, { options, raw, error, spinning: showLoad }),
+    /* @__PURE__ */ jsx15(
+      Header,
+      {
+        options,
+        raw,
+        error,
+        spinning: showLoad,
+        reloadEvery: autoReload2 ? reloadInterval2 : null
+      }
+    ),
     /* @__PURE__ */ jsx15(TabBar, { tab: browse.tab }),
     /* @__PURE__ */ jsx15(
       MainPanel,
@@ -6669,12 +7136,17 @@ function App({
         options,
         saved: saved2,
         noCache: noCache2,
+        autoReload: autoReload2,
+        reloadInterval: reloadInterval2,
+        notifications: notifications2,
+        notifyChannel: notifyChannel2,
         copyLinks: copyLinks2,
         themeState,
         onDraft: (value2) => {
           draftRef.current = value2;
         },
         onSubmitField: commitField,
+        onSubmitReloadInterval: commitReloadInterval,
         onSubmitThemeColor: commitThemeColor,
         onToggleReviewType: (type) => {
           setOptions((previous) => {
@@ -6728,6 +7200,10 @@ function bootstrap() {
       initial: initial2,
       saved: saved2,
       noCache: values["no-cache"],
+      autoReload: settings.autoReload === true,
+      reloadInterval: settings.reloadInterval ?? DEFAULT_RELOAD_INTERVAL,
+      notifications: settings.notifications === true,
+      notifyChannel: settings.notifyChannel ?? "auto",
       copyLinks: settings.copyLinks === true,
       theme: theme3,
       json: values.json
@@ -6742,7 +7218,7 @@ function bootstrap() {
 
 // src/tui/main.tsx
 import { jsx as jsx16 } from "@opentui/react/jsx-runtime";
-var { initial, saved, noCache, copyLinks, theme: theme2, json } = bootstrap();
+var { initial, saved, noCache, autoReload, reloadInterval, notifications, notifyChannel, copyLinks, theme: theme2, json } = bootstrap();
 if (json) {
   await runJsonStats(initial, noCache);
 }
@@ -6761,6 +7237,10 @@ createRoot(renderer).render(
       initial,
       initialSaved: saved,
       initialNoCache: noCache,
+      initialAutoReload: autoReload,
+      initialReloadInterval: reloadInterval,
+      initialNotifications: notifications,
+      initialNotifyChannel: notifyChannel,
       initialCopyLinks: copyLinks,
       initialTheme: theme2,
       onQuit: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3lm/pr-stats",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "GitHub PR stats in an interactive terminal UI, via the gh CLI or an access token",
   "type": "module",
   "author": "Dominic Elm",