github-search-cli 9.10.0 → 9.10.2

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/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;
     }

package/src/tui.ts

@@ -108,7 +108,7 @@ import {
   PACKAGE_SORT_MODES,
   type PackageSortMode,
 } from "./package";
-import { StatusManager } from "./status";
+import { type StatusManager, createStatusManager } from "./status";
 import {
   getNotifications,
   dismissNotification,
@@ -199,6 +199,15 @@ function createTuiLogger(): Logger {
 
 const logger: Logger = createTuiLogger();
 
+// The live StatusManager for the current renderer. Kept at module scope so the
+// hoisted cleanup() can dispose the spinner interval on the quit path; a stale
+// interval would otherwise outlive the destroyed renderable it writes to.
+let activeStatusMgr: StatusManager | null = null;
+// The live renderer, so the hoisted cleanup() can release the terminal
+// (raw mode, alternate screen) before process.exit() — same reasoning as
+// activeStatusMgr above.
+let activeRenderer: CliRenderer | null = null;
+
 // ─── Sort cycle ───────────────────────────────────────────────────────
 const SORT_MODES: { key: SortStrategy; label: string }[] = [
   { key: "best-match", label: "best-match" },
@@ -208,7 +217,10 @@ const SORT_MODES: { key: SortStrategy; label: string }[] = [
 ];
 
 // ─── Main ─────────────────────────────────────────────────────────────
-export async function launchBrowser(theme_override?: string): Promise<void> {
+export async function launchBrowser(
+  theme_override?: string,
+  startMode?: "trending",
+): Promise<void> {
   // Ask the terminal for its real background color (OSC 11) BEFORE the
   // renderer takes over stdin — after that, reading the reply gets messy.
   // Used below so the app backdrop matches the user's terminal theme.
@@ -247,6 +259,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
   }
 
   const root = renderer.root;
+  activeRenderer = renderer;
   root.flexDirection = "column";
 
   // ── Config ──
@@ -692,6 +705,10 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     leaderBox.visible = false;
     leaderDim.visible = false;
     readmeBox.visible = false;
+    // The org panel is a flexGrow sibling of `body` just like every other
+    // overlay — omitting it here meant it stayed visible after Esc, permanently
+    // stealing half the content height and every click in the lower half.
+    orgBox.visible = false;
     updateBox.visible = false;
     updateDim.visible = false;
     if (type === "none") {
@@ -1929,6 +1946,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     },
   });
   const orgText = new TextRenderable(renderer, {
+    ...NON_INTERACTIVE_TEXT,
     content: "",
     fg: colors.text,
     bg: colors.bg,
@@ -1936,6 +1954,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
   orgScroll.add(orgText);
   orgBox.add(orgScroll);
   const orgFooter = new TextRenderable(renderer, {
+    ...NON_INTERACTIVE_TEXT,
     content: "  ↑↓/jk scroll  Esc/q close",
     fg: colors.muted,
     bg: colors.bg,
@@ -2130,10 +2149,16 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     renderer.requestRender();
   };
 
-  const statusMgr = new StatusManager((text) => {
-    statusBar.content = ` ${text}`;
-    renderer.requestRender();
-  });
+  // Held at module scope so cleanup() (a hoisted function declaration, called
+  // from key handlers defined above the manager's creation) can still reach it.
+  activeStatusMgr = createStatusManager(statusBar, () =>
+    renderer.requestRender(),
+  );
+  const statusMgr = activeStatusMgr;
+  // The renderer tears down its renderables on Ctrl+C / SIGTERM / terminal
+  // close, but the 120ms spinner interval is ours. Without this, the next tick
+  // assigns to a destroyed TextBuffer and throws out of a timer callback.
+  renderer.on("destroy", () => statusMgr.dispose());
   setTimeout(() => {
     if (currentOverlay === "none") {
       setStatus(nextTip());
@@ -3433,6 +3458,20 @@ ${pack.description ?? ""}`;
       showOverlay("help");
       return;
     }
+    // Ctrl+E opens the export chooser (CSV / Markdown / JSON / plain text)
+    // straight from the results — the shortcut the startup tip advertises.
+    // Claim the chord first: while the query input is focused its default
+    // emacs binding would otherwise also treat Ctrl+E as "move to line end".
+    if (key.ctrl && key.name === "e") {
+      key.stopPropagation();
+      if (currentRepos.length > 0) {
+        showOverlay("export");
+      } else {
+        setStatus("No results to export — run a search first");
+      }
+      renderer.requestRender();
+      return;
+    }
 
     // Tab auto-completes qualifiers in search input
     if (key.name === "tab") {
@@ -3518,12 +3557,18 @@ ${pack.description ?? ""}`;
   // ── Update check (before start) ──────────────────────────────────────
   const _currentVersion = getVersion();
   // ── Start ──────────────────────────────────────────────────────────
-  // Always start on the landing menu. Saved sessions restore preferences
+  // Default is the landing menu. Saved sessions restore preferences
   // (sort/limit/trending tab) and pre-fill the query once a mode is picked,
   // but never auto-run a search — a stale or corrupted session (e.g. an MCP
   // handshake blob saved as a query) used to hijack startup and skip the
-  // menu on every launch.
-  showLanding(true);
+  // menu on every launch. An explicit `ghfind --trending` is not a stale
+  // session though: it is the mode the user asked for, so it skips the menu.
+  if (startMode === "trending") {
+    showLanding(false);
+    loadTrending();
+  } else {
+    showLanding(true);
+  }
   checkForUpdateAndShow();
   checkPostUpgradePanel();
   renderer.start();
@@ -3549,11 +3594,22 @@ function formatToolbar(
 }
 
 function cleanup(): void {
+  // Stop the spinner before exiting: process.exit() would kill the process
+  // anyway, but a tick already queued between here and the exit can still fire.
+  activeStatusMgr?.dispose();
+  activeStatusMgr = null;
   try {
     rotateHistory();
   } catch {
     /* non-critical */
   }
+  // Release the terminal (raw mode, alternate screen) before the hard exit.
+  try {
+    activeRenderer?.destroy();
+  } catch {
+    /* non-critical */
+  }
+  activeRenderer = null;
   process.exit(0);
 }
 

package/src/watch.ts

@@ -19,6 +19,23 @@ export interface WatchOptions {
   token?: string;
   intervalMs: number;
   trending?: boolean;
+  /** Trending period (`--since`); falls back to the query-string convention. */
+  since?: string;
+}
+
+/**
+ * Resolve the trending period for a watch tick. `--since` wins when it names a
+ * real period; otherwise fall back to the legacy `ghfind --watch weekly`
+ * convention where the query string itself carried the period.
+ */
+export function resolveTrendingSince(
+  opts: Pick<WatchOptions, "query" | "since">,
+): "daily" | "weekly" | "monthly" {
+  if (opts.since === "weekly" || opts.since === "monthly") return opts.since;
+  if (opts.since === "daily") return "daily";
+  if (opts.query === "weekly") return "weekly";
+  if (opts.query === "monthly") return "monthly";
+  return "daily";
 }
 
 const MAX_FAILS = 5;
@@ -44,12 +61,7 @@ export async function runWatch(
     try {
       let repos: Repo[];
       if (opts.trending) {
-        const since =
-          opts.query === "weekly"
-            ? "weekly"
-            : opts.query === "monthly"
-              ? "monthly"
-              : "daily";
+        const since = resolveTrendingSince(opts);
         const trendingSearch = createTrendingSearch();
         const response = await trendingSearch.search(trendingQuery(), {
           limit: opts.limit,

package/src/export.ts

@@ -1,73 +0,0 @@
-/**
- * Export — format repos as JSON, CSV, Markdown, or plain text.
- */
-import { writeFileSync } from "node:fs";
-import type { Repo } from "./types";
-
-export type ExportFormat = "json" | "csv" | "markdown" | "text";
-
-export function formatJson(repos: Repo[]): string {
-  return JSON.stringify(repos, null, 2);
-}
-
-function csvEscape(val: unknown): string {
-  const str = String(val ?? "");
-  if (str.includes('"') || str.includes(",") || str.includes("\n")) {
-    return `"${str.replace(/"/g, '""')}"`;
-  }
-  return str;
-}
-
-/** Format repos as CSV string. */
-export function formatCsv(repos: Repo[]): string {
-  const header = "rank,full_name,stars,forks,language,url";
-  const rows = repos.map(
-    (r, i) =>
-      `${i + 1},${csvEscape(r.fullName)},${r.stars},${r.forks},${csvEscape(r.language ?? "")},${csvEscape(r.url)}`,
-  );
-  return [header, ...rows].join("\n");
-}
-
-/** Format repos as Markdown table. */
-export function formatMarkdown(repos: Repo[]): string {
-  const header = "| # | Repo | Stars | Forks | Language |";
-  const sep = "|---|------|-------|-------|----------|";
-  const rows = repos.map(
-    (r, i) =>
-      `| ${i + 1} | [${r.fullName}](${r.url}) | ${r.stars.toLocaleString()} | ${r.forks.toLocaleString()} | ${r.language ?? "—"} |`,
-  );
-  return [header, sep, ...rows].join("\n");
-}
-
-/** Format repos as plain text, one per line. */
-export function formatText(repos: Repo[]): string {
-  return repos
-    .map(
-      (r, i) =>
-        `${i + 1}. ${r.fullName} ★ ${r.stars.toLocaleString()} ${r.url}`,
-    )
-    .join("\n");
-}
-
-/** Format repos in the given format. */
-export function formatRepos(repos: Repo[], format: ExportFormat): string {
-  switch (format) {
-    case "json":
-      return formatJson(repos);
-    case "csv":
-      return formatCsv(repos);
-    case "markdown":
-      return formatMarkdown(repos);
-    case "text":
-      return formatText(repos);
-  }
-}
-
-/** Export repos to a file. Returns the file path. */
-export function exportToFile(repos: Repo[], format: ExportFormat): string {
-  const ext = format === "markdown" ? "md" : format;
-  const ts = Date.now();
-  const path = `./ghfind-export-${ts}.${ext}`;
-  writeFileSync(path, formatRepos(repos, format), "utf-8");
-  return path;
-}

package/src/pipe.ts

@@ -1,60 +0,0 @@
-/**
- * Pipe-friendly format modifiers — output repo data as lines for shell piping.
- */
-import type { Repo } from "./types";
-import { openUrl } from "./open-url";
-
-export type FormatLine =
-  "urls" | "names" | "ssh-urls" | "clone-commands" | "ids";
-
-export function formatUrls(repos: Repo[]): string {
-  return repos.map((r) => r.url).join("\n");
-}
-
-export function formatNames(repos: Repo[]): string {
-  return repos.map((r) => r.fullName).join("\n");
-}
-
-export function formatSshUrls(repos: Repo[]): string {
-  return repos.map((r) => `git@github.com:${r.fullName}.git`).join("\n");
-}
-
-export function formatCloneCommands(repos: Repo[]): string {
-  return repos
-    .map((r) => `git clone git@github.com:${r.fullName}.git`)
-    .join("\n");
-}
-
-export function formatIds(repos: Repo[]): string {
-  return repos.map((r) => String(r.id)).join("\n");
-}
-
-export function formatLines(repos: Repo[], format: FormatLine): string {
-  switch (format) {
-    case "urls":
-      return formatUrls(repos);
-    case "names":
-      return formatNames(repos);
-    case "ssh-urls":
-      return formatSshUrls(repos);
-    case "clone-commands":
-      return formatCloneCommands(repos);
-    case "ids":
-      return formatIds(repos);
-  }
-}
-
-/** Execute a pipe target (clone, open) on repos. */
-export async function pipeExec(repos: Repo[], target: string): Promise<void> {
-  for (const repo of repos) {
-    const url = repo.url;
-    switch (target) {
-      case "open":
-        await openUrl(url);
-        break;
-      case "clone":
-        console.log(`git clone git@github.com:${repo.fullName}.git`);
-        break;
-    }
-  }
-}