github-search-cli 9.9.0 → 9.10.1

package/docs/HOW-TO.md

@@ -141,8 +141,9 @@ ghfind "cli" --sort forks
 ghfind "cli" --sort best-match # GitHub's own relevance order
 ```
 
-In the TUI, `Space` opens the leader menu, where **Sort** cycles the same
-strategies without leaving the results.
+In the TUI, `Esc` opens the leader menu (or click the <kbd>☰ menu</kbd> button in
+the bottom-right corner), where **Sort** cycles the same strategies without
+leaving the results.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-search-cli",
-  "version": "9.9.0",
-  "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
+  "version": "9.10.1",
+  "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard + mouse TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",
   "volta": {

package/release-notes/9.10.0.md

@@ -0,0 +1,137 @@
+# v9.10.0
+
+ghfind's TUI has always been keyboard-only — and, quietly, half-broken for the
+mouse. OpenTUI was already emitting SGR mouse tracking and hit-testing every
+event into a target renderable. Nothing in ghfind consumed any of it. The
+events were parsed, dispatched, and thrown away. This release makes the TUI
+clickable, and fixes the two keyboard rough edges that were hiding behind it.
+
+## The TUI is now fully clickable
+
+Click a result and the detail pane updates. Click it again and your browser
+opens. Scroll to move through results. Click outside an overlay to close it.
+
+Every list, card, tab and button responds: the results list, the landing mode
+cards, trending tabs, the update dialog's buttons, and every overlay list
+(history, bookmarks, saved searches, topics, export, share, and the command
+menu itself).
+
+The important detail is that clicks do not reimplement anything. A click calls
+`setSelectedIndex`, which emits the same `selectionChanged` event `↑`/`↓`
+already emitted, so the detail pane, the detail graph and the packages view all
+work identically without a parallel code path. A double-click calls the same
+activation path as `Enter`. There is no mouse branch to keep in sync — the
+keyboard and the mouse converge on one implementation, which is also why they
+cannot drift.
+
+## The wheel scrolled the wrong pane
+
+Worth calling out, because it predates this release and was a real bug rather
+than a missing feature.
+
+When a scroll event hit nothing, OpenTUI falls back to delivering it to
+whatever renderable currently holds focus. In ghfind that was almost always the
+results list. So opening the README viewer and scrolling would move the
+_result selection_ instead of the README — the one thing you were trying to do.
+
+Every scrollable region now claims the wheel explicitly, and the list's wheel
+handler steps the selection through `moveUp`/`moveDown`, so wheel navigation
+and `↑`/`↓` navigation cannot diverge either.
+
+## Text that swallowed clicks
+
+`TextRenderable` defaults to OpenTUI's `selectable: true`, and a left-press on
+a selectable renderable is consumed as a text-selection drag _before_ the app's
+own handlers run. The detail pane, comparison table, tab bar and other read-only
+text are all `TextRenderable`s, so clicks landing on them did nothing at all.
+
+They now opt out of text selection. The query input deliberately keeps it, so
+clicking into the input still places your cursor.
+
+## A hover highlight that painted the list magenta
+
+Small one, but it would have been immediately obvious to anyone using it.
+OpenTUI's colour parser accepts `"transparent"`, CSS colour names, and 3/4/6/8
+digit hex — nothing else. An `rgba(255,255,255,0.06)` hover tint failed that
+check and fell through to its magenta fallback, so hovering a list would have
+flashed it magenta. Now written as `#ffffff0f`.
+
+Found because the test harness prints that warning. Worth noting the class of
+bug: OpenTUI degrades an invalid colour to magenta rather than throwing, so this
+fails silently and visibly at the same time.
+
+## `Space` opened the menu only if you had clicked something first
+
+The subtlest problem in this release, and it was not caused by mouse support —
+it was exposed by it.
+
+The query input is focused by default. The command menu was bound to `Space`,
+gated on the input _not_ being focused, so that spaces could still be typed into
+a query. That gate meant `Space` opened the menu only when focus had moved
+somewhere else. The one way focus moved was clicking a result row: OpenTUI's
+auto-focus-on-press walks up from the pressed renderable to the nearest
+focusable ancestor, finds the results list, and focuses it — blurring the input
+as a side effect.
+
+So on a fresh launch, `Space` typed a space. Click any row, and `Space` opened
+the menu. Same key, same screen, different behaviour depending on invisible
+state.
+
+A regression test now pins this down from both directions: with `keepFocus` a row
+click does not move focus, and without it one does.
+
+The resolution is that **`Esc` opens the command menu**, and `Space` always
+types. `Esc` already closed every overlay, so this adds a meaning rather than
+replacing one. For anyone who prefers not to reach for `Esc`, there is now a
+<kbd>☰ menu</kbd> button in the bottom-right corner — clickable, it floats above
+the layout, and it hides while an overlay is open so it never sits on top of one.
+
+## Added
+
+- Full mouse support: click to select, double-click to open, wheel to scroll,
+  click-outside to dismiss, hover feedback with a pointer cursor.
+- <kbd>☰ menu</kbd> button in the bottom-right corner to open the command menu.
+- A "Mouse" section in the in-app help, documenting every binding.
+- README keybinding tables gained a mouse table; the command-menu references
+  across the README and `docs/HOW-TO.md` now say `Esc` instead of `Space`.
+
+## Fixed
+
+- The scroll wheel scrolled the focused renderable rather than the pane under
+  the pointer, so long-pane scrolling moved the result selection instead.
+- Non-interactive text consumed left-presses as text-selection drags, so clicks
+  over the detail pane and comparison table did nothing.
+- The hover tint used an `rgba()` string that OpenTUI's colour parser rejects,
+  rendering the list magenta.
+- `Space` could not open the command menu on a fresh launch, because it was
+  gated on focus that only moved after a mouse click.
+
+## Verification
+
+The suite grew by 33 tests, to 657.
+
+- **15 unit tests** on the click→row geometry: scroll offsets, multi-line rows
+  (overlay lists render a description line, so each option is two lines tall),
+  `itemSpacing`, clicks past the last row, unmeasured renderables, and empty
+  lists. OpenTUI keeps `scrollOffset` and `linesPerItem` private, so this
+  arithmetic is read through a single narrow cast — the tests are what keep that
+  cast honest.
+- **12 integration tests** driving the real handlers with OpenTUI's mock mouse
+  against a live renderer: click-selects, double-click-opens, the double-click
+  window expiring, click-outside dismissal, row clicks _not_ leaking to the
+  enclosing panel, focus behaviour with and without `keepFocus`, and wheel
+  stepping including both ends of the list.
+- **4 button tests** asserting the corner button actually lands in the
+  bottom-right, that hidden buttons neither render nor take clicks, and that its
+  click does not bubble.
+
+The first two geometry tests failed on the run that wrote them, and caught a
+real off-by-one: the empty area below a short list returned "no row" instead of
+resolving to the last row, which would have dismissed an overlay instead of
+selecting its final entry. That is the exact class of bug that would have been
+very annoying and very hard to report.
+
+`test`, `format:check`, `lint` (Biome) and `typecheck` (tsc) are all green, and
+`bun run build` succeeds. The TUI was also driven end-to-end in a pty to confirm
+the menu opens from both `Esc` and the corner button, since the mock mouse does
+not exercise a real terminal's mouse reporting.

package/release-notes/9.10.1.md

@@ -0,0 +1,59 @@
+# v9.10.1
+
+A bug-fix release, found by crawling the whole source against its own docs.
+Three of the eight issues were the kind that quietly cost you time: a flag
+that was documented everywhere but never parsed, a typo that opened a GitHub
+issue tab instead of printing an error, and an empty query that came back as
+a network problem you didn't have.
+
+## `--interval` was never parsed
+
+`--interval` appeared in `--help`, the README, the how-to guide and all
+three shell completions. `parseArgs` had no case for it. So
+`ghfind --watch --interval 60` searched for the literal string
+`"--interval 60"` and polled at the default 300s anyway. It now parses a
+positive whole number of seconds — and rejects anything else with a message
+instead of a mangled query.
+
+## A typo used to open a GitHub issue tab
+
+`--format jsonn` threw `Unknown format` from inside the run, which the top
+level error handler classified as unexpected: it printed "ghfind encountered
+an unexpected error" and opened a prefilled GitHub issue page in your
+browser. `--pipe clonee` was the opposite failure — it did nothing at all
+and exited 0.
+
+Both flags now validate up front, print the list of valid values, and exit 1
+before any search happens.
+
+## An empty query was a network error
+
+`ghfind --count` with no query sent `q=" "` to GitHub, got a 422 back, and
+surfaced it as `⚠ Network error — check your connection. Retrying in 5s...`
+— a connectivity problem you didn't have, on a loop. The search, format,
+pipe and watch handlers now fail fast with a usage hint instead.
+
+## The rest
+
+- **Bare `ghfind --trending` opens the trending view.** It used to fall
+  through to the landing menu, contradicting TRACKER.md.
+- **`--since` validates its value** (`daily|weekly|monthly`) instead of
+  silently falling back to daily — the same treatment `--sort` already had.
+- **Watch mode honors `--since`.** The trending period was derived from the
+  query string, so `--watch --trending --since weekly` polled daily. An
+  explicit `--since` wins; the query-string convention still works when the
+  flag is absent.
+- **The MCP `ghfind_user_profile` tool returns formatted text**, matching
+  `ghfind_org_profile` and the CLI's default `ghfind user` output — the raw
+  JSON still rides along in `data`.
+- **The trending footer matches its `/` key** (`/ top` — it scrolls to the
+  top, it never opened search), and the quit paths of the main TUI, trending
+  and package browser now call `renderer.destroy()` before exiting, so the
+  terminal is released properly.
+
+## Removed
+
+Dead code with no importers: `src/search-state.ts` (still referenced the
+pre-unification `config.githubTokens`), `src/export.ts` and `src/pipe.ts`
+(byte-for-byte duplicates of `src/output.ts`, which is what everything
+imports), and the unused `historyCount()` export.

package/src/cli.ts

@@ -25,6 +25,8 @@ import { reportError } from "./error-report";
 import {
   format as formatOutput,
   pipeExec,
+  FORMAT_VALUES,
+  PIPE_TARGETS,
   type Format,
   type ExportFormat,
 } from "./output";
@@ -104,6 +106,8 @@ interface CLIFlags {
   token?: string;
   trending: boolean;
   since: string;
+  /** True when --since was passed (watch falls back to the query-string convention otherwise). */
+  sinceExplicit: boolean;
   pipe?: string;
   format?: string;
   watch: boolean;
@@ -156,6 +160,9 @@ const SORT_VALUES = [
   "name",
 ];
 
+/** Valid `--since` values — the periods github.com/trending accepts. */
+const SINCE_VALUES: readonly string[] = ["daily", "weekly", "monthly"];
+
 function parseArgs(args: string[]): CLIFlags {
   const flags: CLIFlags = {
     query: "",
@@ -168,6 +175,7 @@ function parseArgs(args: string[]): CLIFlags {
     token: process.env.GITHUB_TOKEN,
     trending: false,
     since: "daily",
+    sinceExplicit: false,
     watch: false,
     releases: false,
     interval: 300,
@@ -276,15 +284,51 @@ function parseArgs(args: string[]): CLIFlags {
       case "--token":
         flags.token = args[++i];
         break;
-      case "--since":
-        flags.since = args[++i];
+      case "--interval": {
+        const parsed = parseInt(args[++i], 10);
+        if (Number.isNaN(parsed) || parsed < 1) {
+          console.error(
+            `Invalid interval: ${args[i] ?? "(missing)"} (must be a whole number of seconds, e.g. 300).`,
+          );
+          process.exit(1);
+        }
+        flags.interval = parsed;
         break;
-      case "--pipe":
-        flags.pipe = args[++i];
+      }
+      case "--since": {
+        const since = args[++i];
+        if (!since || !SINCE_VALUES.includes(since)) {
+          console.error(
+            `Invalid since: ${since ?? "(missing)"} (use daily|weekly|monthly).`,
+          );
+          process.exit(1);
+        }
+        flags.since = since;
+        flags.sinceExplicit = true;
         break;
-      case "--format":
-        flags.format = args[++i];
+      }
+      case "--pipe": {
+        const target = args[++i];
+        if (!target || !PIPE_TARGETS.includes(target)) {
+          console.error(
+            `Invalid pipe target: ${target ?? "(missing)"} (use open|clone).`,
+          );
+          process.exit(1);
+        }
+        flags.pipe = target;
+        break;
+      }
+      case "--format": {
+        const fmt = args[++i];
+        if (!fmt || !FORMAT_VALUES.includes(fmt)) {
+          console.error(
+            `Invalid format: ${fmt ?? "(missing)"} (use ${FORMAT_VALUES.join("|")}).`,
+          );
+          process.exit(1);
+        }
+        flags.format = fmt;
         break;
+      }
       case "--registry":
         flags.registry = args[++i] ?? "npm";
         break;
@@ -636,7 +680,13 @@ Options:
     return;
   }
 
-  await launchBrowser(flags.theme);
+  await launchBrowser(
+    flags.theme,
+    // `ghfind --trending` with no query/format promises the trending view
+    // (TRACKER.md), but the bare flag used to fall through to the landing
+    // menu. An explicit flag is explicit intent — skip the menu.
+    flags.trending ? "trending" : undefined,
+  );
 }
 
 interface SearchContext {
@@ -1197,6 +1247,7 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
           token: flags.token,
           intervalMs: flags.interval * 1000,
           trending: flags.trending,
+          since: flags.sinceExplicit ? flags.since : undefined,
         },
         (repos, delta) => {
           tick++;
@@ -1298,6 +1349,25 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
               ? "format"
               : "search";
 
+  // The search/format/pipe/watch handlers all need a query. Without this
+  // gate an empty query was sent to GitHub as `q=" "`, which returns 422 and
+  // surfaced to the user as a misleading "Network error — check your
+  // connection" retry loop.
+  const needsQuery =
+    key === "search" ||
+    key === "format" ||
+    key === "pipe" ||
+    (key === "watch" && !flags.trending);
+  if (needsQuery && flags.query.trim() === "") {
+    console.error("⚠ No search query given.");
+    console.error(
+      '  Usage: ghfind "<query>" [--count|--format <fmt>|--pipe <tgt>|--watch]',
+    );
+    console.error('  Example: ghfind "language:Rust stars:>500" --count');
+    console.error("  Run `ghfind --help` for all options.");
+    process.exit(1);
+  }
+
   const ctx = buildSearchContext(flags);
   await handlers[key](ctx);
 }

package/src/help.ts

@@ -30,7 +30,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "↑ ↓ / j k", action: "Move selection" },
         { keys: "Enter", action: "Open repo in browser" },
         { keys: "/", action: "Focus search input" },
-        { keys: "Space", action: "Open command menu" },
+        { keys: "Esc", action: "Open command menu" },
         { keys: "? / Ctrl+H", action: "Toggle this help screen" },
         { keys: "q", action: "Quit" },
       ],
@@ -65,6 +65,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "1-5", action: "Switch tab: Today → Week → Month → …" },
         { keys: "← → / h l", action: "Navigate tabs" },
       ],
+      note: "Tabs are also clickable.",
     },
     {
       title: " Packages Mode ",
@@ -73,12 +74,12 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "/", action: "Search npm packages" },
         { keys: "↑ ↓ / j k", action: "Move selection" },
         { keys: "Enter", action: "View package details" },
-        { keys: "Space", action: "Open command menu" },
+        { keys: "Esc", action: "Open command menu" },
       ],
       note: "Search by name, description, or tags. Sort by downloads or score.",
     },
     {
-      title: " Command Menu (Space)",
+      title: " Command Menu (Esc)",
       titleColor: "purple",
       rows: [
         { keys: "Sort", action: "Cycle sort: best-match → stars → …" },
@@ -103,7 +104,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "History", action: "View search history" },
         { keys: "Help", action: "Show this help screen" },
       ],
-      note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc",
+      note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc. Clicking a row runs it directly. Esc (or the ☰ menu button) opens this menu; Space types a space in the query.",
     },
     {
       title: " Bookmarks Page ",
@@ -116,6 +117,22 @@ export function buildHelpSections(): HelpSection[] {
       ],
       note: "A full page, not an overlay — Esc returns to the mode menu.",
     },
+    {
+      title: " Mouse ",
+      titleColor: "green",
+      rows: [
+        { keys: "Click", action: "Select a row / card / tab" },
+        { keys: "Double-click", action: "Open the repo or run the action" },
+        { keys: "Scroll wheel", action: "Move the selection / scroll a pane" },
+        { keys: "Click outside", action: "Dismiss an open overlay" },
+        { keys: "Click query box", action: "Focus the search input" },
+        {
+          keys: "☰ menu button",
+          action: "Open the command menu (bottom-right)",
+        },
+      ],
+      note: "Every list is fully clickable; keyboard and mouse are interchangeable.",
+    },
     {
       title: " Overlay Keys ",
       titleColor: "teal",

package/src/history.ts

@@ -29,6 +29,10 @@ export function readHistory(): HistoryEntry[] {
 
 /** Delete a single history entry by index (0 = newest). */
 export function deleteHistoryEntry(index: number): void {
+  // The index comes from the overlay, which lists readHistory()'s deduplicated
+  // newest-first view — so delete against that same view. Raw lines can't be
+  // addressed by this index: consecutive duplicate queries are collapsed in
+  // the view, which shifts every raw-line position after them.
   const entries = readHistory();
   if (index < 0 || index >= entries.length) return;
   entries.splice(index, 1);
@@ -59,8 +63,3 @@ export function rotateHistory(): void {
       .join("\n")}\n`,
   );
 }
-
-/** Count entries in history file. */
-export function historyCount(): number {
-  return readJSONL<HistoryEntry>(HISTORY_FILE).length;
-}

package/src/mcp-server.ts

@@ -38,7 +38,7 @@ import {
   type PackageSortMode,
 } from "./package";
 import { fetchOrgProfile, formatOrgText } from "./org";
-import { fetchUserProfile, formatUserJson } from "./user";
+import { fetchUserProfile, formatUserText } from "./user";
 import {
   fetchDeepDive,
   buildDeepDiveText,
@@ -511,7 +511,9 @@ const TOOLS: ToolDefinition[] = [
         token: resolveToken(state, args.token),
         limit,
       });
-      return { text: formatUserJson(profile), data: { ...profile } };
+      // Human-readable text like ghfind_org_profile (the structured data
+      // still rides along in `data` for callers that want the raw numbers).
+      return { text: formatUserText(profile), data: { ...profile } };
     },
   },
   {

package/src/output.ts

@@ -22,8 +22,11 @@ export type Format =
 
 export type FormatFn = (repos: Repo[]) => string;
 
+/** Accepted `--pipe` targets — the cases `pipeExec` actually handles. */
+export const PIPE_TARGETS: readonly string[] = ["open", "clone"];
+
 /** Registry of all format functions. Adding a format = 1 line here. */
-const FORMATS: Map<Format, FormatFn> = new Map([
+const FORMATS: Map<Format, FormatFn> = new Map<Format, FormatFn>([
   // Export formats
   ["json", formatJson],
   ["csv", formatCsv],
@@ -37,6 +40,13 @@ const FORMATS: Map<Format, FormatFn> = new Map([
   ["ids", formatIds],
 ]);
 
+/**
+ * Every accepted `--format` value, derived from the registry above so the CLI
+ * can validate up front instead of throwing `Unknown format` mid-run (a plain
+ * typo used to route into the crash-report flow).
+ */
+export const FORMAT_VALUES: readonly string[] = [...FORMATS.keys()];
+
 // ── Export format functions ────────────────────────────────────────────
 
 export function formatJson(repos: Repo[]): string {

package/src/package-browser.ts

@@ -265,6 +265,8 @@ export async function launchPackageBrowser(): Promise<void> {
   renderer.keyInput.on("keypress", (key: import("@opentui/core").KeyEvent) => {
     const name = key.name || "";
     if (name === "q" || name === "escape") {
+      // Release the terminal before the hard exit, same as the main TUI.
+      renderer.destroy();
       process.exit(0);
       return;
     }

package/src/status.ts

@@ -12,12 +12,16 @@ export class StatusManager {
   private type: StatusType = "idle";
   private message = "";
   private onUpdate: (text: string) => void;
+  private disposed = false;
 
   constructor(onUpdate: (text: string) => void) {
     this.onUpdate = onUpdate;
   }
 
   set(type: StatusType, message: string): void {
+    // Late async continuations (a search resolving after quit) can call
+    // set() long after the UI is gone; a disposed manager is inert.
+    if (this.disposed) return;
     this.stopSpinner();
     this.type = type;
     this.message = message;
@@ -32,6 +36,7 @@ export class StatusManager {
   }
 
   private startSpinner(frames: string[]): void {
+    if (this.disposed) return;
     this.spinnerIndex = 0;
     this.emit(frames[0]);
     this.spinnerInterval = setInterval(() => {
@@ -48,6 +53,8 @@ export class StatusManager {
   }
 
   private emit(spinner?: string): void {
+    // A tick can already be queued when dispose() clears the interval.
+    if (this.disposed) return;
     const icon =
       this.type === "searching"
         ? "🔍"
@@ -63,6 +70,39 @@ export class StatusManager {
   }
 
   dispose(): void {
+    this.disposed = true;
     this.stopSpinner();
   }
 }
+
+/**
+ * The status-bar renderable, narrowed to what the manager needs. TextRenderable
+ * satisfies this structurally (isDestroyed is a public getter on Renderable).
+ */
+export interface StatusBarTarget {
+  readonly isDestroyed: boolean;
+  // Accessor pair, not `content: string`: TextRenderable's getter widens to
+  // StyledText while its setter accepts a plain string. `unknown` on the read
+  // side keeps the renderable assignable; we only ever write strings.
+  get content(): unknown;
+  set content(value: string);
+}
+
+/**
+ * Build a StatusManager wired to a status bar, plus a hook to request a frame.
+ *
+ * Writes are dropped once the renderable is destroyed. The renderer tears its
+ * tree down on Ctrl+C / SIGTERM / terminal close but leaves the event loop
+ * running, so an unguarded spinner tick would assign to a destroyed TextBuffer
+ * and throw out of a timer callback, taking the whole process with it.
+ */
+export function createStatusManager(
+  bar: StatusBarTarget,
+  onFrame: () => void,
+): StatusManager {
+  return new StatusManager((text) => {
+    if (bar.isDestroyed) return;
+    bar.content = ` ${text}`;
+    onFrame();
+  });
+}

package/src/trending.ts

@@ -398,7 +398,7 @@ export async function launchTrending(): Promise<void> {
     paddingX: 1,
   });
   const footerText = new TextRenderable(renderer, {
-    content: " ↑↓ navigate  ↵ open  / search  1-3 tab  q quit  r refresh",
+    content: " ↑↓ navigate  ↵ open  / top  1-3 tab  q quit  r refresh",
     fg: C.muted,
     height: 1,
   });
@@ -430,6 +430,8 @@ export async function launchTrending(): Promise<void> {
   renderer.keyInput.on("keypress", (key) => {
     const name = key.name || "";
     if (name === "q") {
+      // Release the terminal before the hard exit, same as the main TUI.
+      renderer.destroy();
       process.exit(0);
       return;
     }