github-search-cli 9.8.2 → 9.9.0

package/src/session.ts

@@ -6,9 +6,63 @@ import { readJSON, writeJSON } from "./storage";
 
 const SESSION_FILE = "session.json";
 
+/** Upper bound for a plausible search query; anything longer is garbage. */
+const MAX_QUERY_LENGTH = 200;
+
+/**
+ * Drop JSON-shaped or oversized queries. A search line is never raw JSON
+ * (objects/arrays always arrive as paste payloads — e.g. an MCP handshake
+ * request that a client piped into the TUI) and never thousands of chars,
+ * so such a "query" is corruption, not intent. The TUI's input handler
+ * applies the same shape rule to live pastes.
+ */
+export function sanitizeQuery(query: unknown): string | undefined {
+  if (typeof query !== "string") return undefined;
+  const trimmed = query.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_QUERY_LENGTH) {
+    return undefined;
+  }
+  if (
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith("[") && trimmed.endsWith("]"))
+  ) {
+    return undefined;
+  }
+  return trimmed;
+}
+
+/** Keep only well-formed, known-good fields from a session snapshot. */
+export function sanitizeSession(
+  state: SessionState | null | undefined,
+): SessionState | null {
+  if (!state || typeof state !== "object") return null;
+  const mode =
+    state.mode === "trending" ||
+    state.mode === "packages" ||
+    state.mode === "search"
+      ? state.mode
+      : "search";
+  const trendingTab =
+    typeof state.trendingTab === "string" && state.trendingTab.length > 0
+      ? state.trendingTab
+      : "This Week";
+  const limit =
+    typeof state.limit === "number" && Number.isFinite(state.limit)
+      ? state.limit
+      : 50;
+  const sort = typeof state.sort === "string" ? state.sort : "best-match";
+  return {
+    mode,
+    query: sanitizeQuery(state.query) ?? "",
+    sort,
+    limit,
+    trendingTab,
+  };
+}
+
 export function saveSession(state: SessionState): void {
   try {
-    writeJSON(SESSION_FILE, state);
+    writeJSON(SESSION_FILE, sanitizeSession(state));
   } catch (err) {
     if (process.env.DEBUG)
       console.error(
@@ -18,7 +72,9 @@ export function saveSession(state: SessionState): void {
 }
 
 export function restoreSession(): SessionState | null {
-  return readJSON<SessionState | null>(SESSION_FILE, null);
+  // Anything read from disk passes the same sanitizer as anything written —
+  // protects against files corrupted before this guard existed.
+  return sanitizeSession(readJSON<SessionState | null>(SESSION_FILE, null));
 }
 
 export function clearSession(): void {

package/src/trending.ts

@@ -14,7 +14,7 @@ import {
 import type { CliRenderer } from "@opentui/core";
 import type { Repo, ParsedQuery } from "./types";
 import { openUrl } from "./open-url";
-import { SearchModule, TrendingAdapter } from "./search";
+import { SearchModule, TrendingAdapter, trendingQuery } from "./search";
 import { detectTerminalBackground, deriveSurfaceLayers } from "./themes";
 // ─── Tokyo Night palette ──────────────────────────────────────────────
 const C = {
@@ -207,11 +207,7 @@ export async function launchTrending(): Promise<void> {
     renderer.requestRender();
     try {
       const searchModule = new SearchModule(new TrendingAdapter());
-      const parsed: ParsedQuery = {
-        keywords: [],
-        qualifiers: [],
-        raw: "trending",
-      };
+      const parsed: ParsedQuery = trendingQuery();
       const response = await searchModule.search(parsed, {
         limit: 25,
         sort: "stars",

package/src/tui.ts

@@ -31,6 +31,7 @@ import {
   SelectRenderable,
   ScrollBoxRenderable,
 } from "@opentui/core";
+import { appendFileSync } from "node:fs";
 import type { CliRenderer } from "@opentui/core";
 import type {
   Repo,
@@ -47,6 +48,8 @@ import {
   applyFlagFilters,
   validateQuery,
   suggestFor,
+  suggestRelaxations,
+  trendingQuery,
   rankRepos,
   createGitHubSearch,
   SearchModule,
@@ -56,7 +59,14 @@ import {
 import { tabSince, TAB_NAMES, fmtStars } from "./trending";
 import { loadConfig, saveConfig } from "./config";
 import { buildHelpSections, HELP_KEYS_COLUMN } from "./help";
-import { SearchCliError, NoResultsError } from "./errors";
+import {
+  SearchCliError,
+  NoResultsError,
+  NetworkError,
+  RateLimitError,
+  AuthError,
+  ForbiddenError,
+} from "./errors";
 import {
   appendHistory,
   readHistory,
@@ -113,6 +123,7 @@ import {
   fetchReleaseNotes,
   readUpdateState,
   recordPreUpdateState,
+  markPostUpgradeSeen,
 } from "./update-check";
 import { debugLog } from "./storage";
 import {
@@ -145,12 +156,41 @@ const colors: Record<string, string> = {
 };
 
 // ─── Logger ───────────────────────────────────────────────────────────
-const logger: Logger = {
-  debug: () => {},
-  info: () => {},
-  warn: () => {},
-  error: () => {},
-};
+/**
+ * TUI diagnostic log.
+ *
+ * The TUI owns the screen, so it cannot print debug output to stdout without
+ * corrupting the render — and the logger used to be a silent no-op, which made
+ * API failures (403/401) undiagnosable from the status-bar message alone.
+ *
+ * Set GHFIND_LOG=<path> to append timestamped lines to that file. Unset (the
+ * default) keeps logging completely off, so there is no cost in normal use.
+ * Only the shape of a response is recorded; tokens and headers are redacted.
+ */
+function createTuiLogger(): Logger {
+  const target = process.env.GHFIND_LOG;
+  if (!target) {
+    return { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} };
+  }
+  const write = (level: string, msg: string) => {
+    try {
+      appendFileSync(
+        target,
+        `[${new Date().toISOString()}] [${level}] ${msg}\n`,
+      );
+    } catch {
+      // A broken log path must never take down the TUI.
+    }
+  };
+  return {
+    debug: (m) => write("debug", m),
+    info: (m) => write("info", m),
+    warn: (m) => write("warn", m),
+    error: (m) => write("error", m),
+  };
+}
+
+const logger: Logger = createTuiLogger();
 
 // ─── Sort cycle ───────────────────────────────────────────────────────
 const SORT_MODES: { key: SortStrategy; label: string }[] = [
@@ -204,7 +244,10 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
 
   // ── Config ──
   const config = loadConfig();
-  const githubToken = config.githubToken || process.env.GITHUB_TOKEN;
+  // Mutable: the AuthError flow lets the user fix or clear the token without
+  // restarting (the next search re-reads this variable).
+  let githubToken: string | undefined =
+    config.githubToken || process.env.GITHUB_TOKEN;
 
   // Apply theme
   const theme = loadTheme(theme_override || config.theme);
@@ -438,6 +481,11 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
         currentMode = "search";
         showLanding(false);
         showSearchMode();
+        // Restore the saved query (if any) as a prefill, never auto-run it.
+        if (currentQueryInput) {
+          searchInput.value = currentQueryInput;
+          renderer.requestRender();
+        }
       },
     },
     {
@@ -1610,6 +1658,9 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     if (state.lastInstalledVersion === currentVersion) return;
     // We just upgraded — show notes for the new version
     const notes = fetchReleaseNotes(currentVersion);
+    // Acknowledge immediately: this panel's trigger is a version inequality,
+    // so leaving it unacknowledged makes it reappear on every launch.
+    markPostUpgradeSeen(currentVersion);
     updateSelectedOption = 0;
     updateHeader.content = `  Updated ghfind ${state.lastInstalledVersion} → ${currentVersion}\n`;
     updateNotes.setContent(
@@ -1923,12 +1974,125 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     }
   }, 2000);
 
+  // ── Token fix flow (from 401/403 error hints) ───────────────────────
+  // Inline prompt box that slides over the search input row. Enter saves the
+  // token to config and re-runs the failed query; Esc cancels.
+  const tokenPromptBox = new BoxRenderable(renderer, {
+    visible: false,
+    position: "absolute",
+    top: 0,
+    left: 0,
+    width: "100%",
+    flexDirection: "row",
+    paddingY: 1,
+    paddingLeft: 1,
+    backgroundColor: colors.surface,
+  });
+  const tokenPromptLabel = new TextRenderable(renderer, {
+    content: " GitHub token:",
+    fg: colors.accent,
+    height: 1,
+  });
+  const tokenPromptInput = new InputRenderable(renderer, {
+    placeholder: "paste token, Enter to save — Esc cancels",
+    value: "",
+    backgroundColor: colors.surface,
+    textColor: colors.text,
+    flexGrow: 1,
+  });
+  tokenPromptBox.add(tokenPromptLabel);
+  tokenPromptBox.add(tokenPromptInput);
+  root.add(tokenPromptBox);
+
+  let tokenPromptQuery: string | null = null;
+
+  function showTokenPrompt(query: string) {
+    tokenPromptQuery = query;
+    tokenPromptInput.value = "";
+    tokenPromptBox.visible = true;
+    searchBox.visible = false;
+    tokenPromptInput.focus();
+    renderer.requestRender();
+  }
+
+  function hideTokenPrompt() {
+    tokenPromptBox.visible = false;
+    tokenPromptQuery = null;
+    if (currentMode === "search" || currentMode === "packages") {
+      searchBox.visible = true;
+      searchInput.focus();
+    }
+    renderer.requestRender();
+  }
+
+  function persistToken(token: string): void {
+    githubToken = token;
+    config.githubToken = token;
+    saveConfig(config);
+  }
+
+  tokenPromptInput.on("enter", () => {
+    const token = tokenPromptInput.value.trim();
+    const query = tokenPromptQuery;
+    hideTokenPrompt();
+    if (!token || !query) return;
+    persistToken(token);
+    setStatus("Token saved");
+    doSearch(query);
+  });
+
+  // ── Error-hint key actions ([t] fix token, [u] unset) ──────────────
+
+  function fixTokenAction() {
+    showTokenPrompt(currentQueryInput || "stars:>10000");
+  }
+
+  function unsetTokenAction() {
+    githubToken = undefined;
+    if (config.githubToken) {
+      delete config.githubToken;
+      saveConfig(config);
+    }
+    setStatus("Token cleared — searching without one");
+    if (currentQueryInput) doSearch(currentQueryInput);
+  }
+
   // ── Helper functions ────────────────────────────────────────────────
 
   function setStatus(msg: string) {
     statusMgr.set("idle", msg);
   }
 
+  /**
+   * Which error family is showing in the status bar, for the bracketed key
+   * hints the messages advertise ([r]etry, [t]/[c] token, [u]nset).
+   * Null once the next search starts, so the hint keys can't hijack
+   * theme/compare forever after a transient failure.
+   */
+  type ErrorHintKind = "auth" | "forbidden" | "ratelimit" | "network" | null;
+  let errorHint: ErrorHintKind = null;
+
+  /** Render an error in the status bar and remember which hints apply. */
+  function reportError(err: unknown) {
+    errorHint =
+      err instanceof AuthError
+        ? "auth"
+        : err instanceof ForbiddenError
+          ? "forbidden"
+          : err instanceof RateLimitError
+            ? "ratelimit"
+            : err instanceof NetworkError
+              ? "network"
+              : null;
+    const msg =
+      err instanceof SearchCliError
+        ? err.userMessage
+        : err instanceof Error
+          ? err.message
+          : String(err);
+    statusMgr.set("error", msg.slice(0, 60));
+  }
+
   /** Session snapshot; only restorable modes are persisted (see SessionState). */
   function buildSessionState(): SessionState {
     const mode: SessionState["mode"] =
@@ -2222,6 +2386,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
   async function loadTrending() {
     currentMode = "trending";
     isLoading = true;
+    errorHint = null;
     searchBox.visible = false;
     toolbarText.visible = false;
     trendingTabBox.visible = true;
@@ -2236,16 +2401,13 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
 
     try {
       const searchModule = new SearchModule(new TrendingAdapter());
-      const response = await searchModule.search(
-        { keywords: [], qualifiers: [], raw: "trending" },
-        {
-          limit: 25,
-          sort: "stars",
-          json: false,
-          verbose: false,
-          trendingSince: tabSince(trendingTab),
-        },
-      );
+      const response = await searchModule.search(trendingQuery(), {
+        limit: 25,
+        sort: "stars",
+        json: false,
+        verbose: false,
+        trendingSince: tabSince(trendingTab),
+      });
       const fetched = response.repos;
       const since = tabSince(trendingTab);
       trendingPeriod =
@@ -2277,16 +2439,10 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
         resultCount: fetched.length,
       });
     } catch (err) {
-      const msg =
-        err instanceof SearchCliError
-          ? err.userMessage
-          : err instanceof Error
-            ? err.message
-            : String(err);
       resultsSelect.options = [
         { name: " (error)", description: "", value: null },
       ];
-      statusMgr.set("error", msg.slice(0, 60));
+      reportError(err);
     }
     isLoading = false;
     renderer.requestRender();
@@ -2329,6 +2485,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     if (q === "" || isLoading) return;
     currentQueryInput = q;
     isLoading = true;
+    errorHint = null; // npm errors never carry GitHub auth hints
     resultsSelect.options = [
       { name: "  Searching packages...", description: "", value: null },
     ];
@@ -2367,6 +2524,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     const q = queryText.trim();
     if (q === "" || isLoading) return;
 
+    errorHint = null; // a fresh search retires the previous error's hint keys
     if (!append) currentPage = 1;
     deepDiveActive = false;
 
@@ -2403,7 +2561,12 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
       }
 
       if (currentRepos.length === 0) {
-        throw new NoResultsError(q);
+        // A zero-result search usually means one qualifier over-constrained
+        // it. Offer the ranked loosenings instead of generic advice.
+        throw new NoResultsError(
+          q,
+          suggestRelaxations(parsed).map((r) => r.suggestion),
+        );
       } else {
         resultsSelect.options = currentRepos.map((r) => ({
           name: formatResultLine(r),
@@ -2434,13 +2597,7 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
           { name: " (error)", description: "", value: null },
         ];
       }
-      const msg =
-        err instanceof SearchCliError
-          ? err.userMessage
-          : err instanceof Error
-            ? err.message
-            : String(err);
-      statusMgr.set("error", msg.slice(0, 60));
+      reportError(err);
     }
 
     isLoading = false;
@@ -2558,6 +2715,18 @@ ${pack.description ?? ""}`;
 
   // ── Global keyboard shortcuts ──────────────────────────────────────
   renderer.keyInput.on("keypress", (key) => {
+    // ── Token prompt (own keyboard scope) ──────────────────────────
+    if (tokenPromptBox.visible) {
+      if (key.name === "escape") {
+        hideTokenPrompt();
+        setStatus("Token entry cancelled");
+        renderer.requestRender();
+        return;
+      }
+      if (key.name === "enter" || key.name === "return") return; // InputRenderable fires "enter"
+      return; // let the input consume everything else (letters, paste, etc.)
+    }
+
     // ── Overlay-mode handling ────────────────────────────────────────
     if (currentOverlay !== "none") {
       // Escape or q closes any overlay (except: leader uses Esc for back-nav, q to close)
@@ -2930,6 +3099,34 @@ ${pack.description ?? ""}`;
       return;
     }
 
+    // Error-hint keys — active only while a status-bar error that advertises
+    // them ([r]etry / [t]oken / [u]nset / [c]ycle) is on screen; the next
+    // search clears the state, returning t/c to their normal roles.
+    if (!searchInput.focused && errorHint) {
+      if (key.name === "r") {
+        errorHint = null;
+        if (currentMode === "trending") loadTrending();
+        else if (currentQueryInput) doSearch(currentQueryInput);
+        renderer.requestRender();
+        return;
+      }
+      if (
+        key.name === "t" &&
+        (errorHint === "auth" || errorHint === "forbidden")
+      ) {
+        fixTokenAction();
+        return;
+      }
+      if (key.name === "u" && errorHint === "auth") {
+        unsetTokenAction();
+        return;
+      }
+      if (key.name === "c" && errorHint === "ratelimit") {
+        fixTokenAction(); // TUI manages a single token — prompt for a different one
+        return;
+      }
+    }
+
     // 't' toggles theme and persists to config
     if (key.name === "t" && !searchInput.focused) {
       const current = config.theme;
@@ -3049,26 +3246,15 @@ ${pack.description ?? ""}`;
   // ── Update check (before start) ──────────────────────────────────────
   const _currentVersion = getVersion();
   // ── Start ──────────────────────────────────────────────────────────
-  // Check for updates (non-blocking — doesn't delay TUI startup)
-  if (!session?.mode) {
-    showLanding(true);
-  }
+  // Always start on 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);
   checkForUpdateAndShow();
   checkPostUpgradePanel();
   renderer.start();
-  if (session?.mode) {
-    if (currentMode === "trending") {
-      loadTrending();
-    } else {
-      searchInput.value = currentQueryInput;
-      if (currentQueryInput) {
-        doSearch(currentQueryInput);
-      } else {
-        showSearchMode();
-      }
-      searchInput.focus();
-    }
-  }
   renderer.requestRender();
 }
 

package/src/types.ts

@@ -10,14 +10,24 @@ export interface Qualifier {
   negated: boolean;
 }
 
+/** A normalization applied to a qualifier while parsing (typo fix, `10k` → `>=10000`). */
+export interface QueryCorrection {
+  /** What the user typed, e.g. `langauge:rust`. */
+  from: string;
+  /** What it was normalized to, e.g. `language:Rust`. */
+  to: string;
+}
+
 /** The fully parsed, normalized representation of a user's search request. */
 export interface ParsedQuery {
   /** Free-text keywords (everything that is not a qualifier). */
   keywords: string[];
-  /** Structured qualifiers extracted from the query string. */
+  /** Structured qualifiers extracted from the query string, normalized. */
   qualifiers: Qualifier[];
   /** The original, untouched query string (preserved for debugging/display). */
   raw: string;
+  /** Normalizations applied while parsing. Empty when the query was already canonical. */
+  corrections: QueryCorrection[];
 }
 
 /** A repository as returned by a search provider, normalized to a stable shape. */

package/src/update-check.ts

@@ -59,6 +59,32 @@ export function shouldCheckUpdate(): boolean {
   return true;
 }
 
+/**
+ * Split a semver string into comparable numeric parts.
+ *
+ * A leading `v` is tolerated. Pre-release (`-beta.1`) and build (`+build.5`)
+ * suffixes are both stripped first, so `9.9.0+build.5` and `9.9.0` compare as
+ * the same release — leaving them in makes `Number("0+build")` NaN.
+ */
+function semverParts(v: string): number[] {
+  const core = v.trim().replace(/^v/i, "").split(/[-+]/)[0];
+  return core.split(".").map((s) => {
+    const n = Number(s);
+    return Number.isFinite(n) ? n : 0;
+  });
+}
+
+/**
+ * True when `v` carries a pre-release tag (`-beta.1`, `-rc.2`, …).
+ * npm semantics: a pre-release is OLDER than the matching release.
+ */
+function isPrerelease(v: string): boolean {
+  const core = v.trim().replace(/^v/i, "");
+  const plus = core.indexOf("+");
+  const coreOnly = plus === -1 ? core : core.slice(0, plus);
+  return coreOnly.includes("-");
+}
+
 /**
  * Compare two semver strings. Returns true if `latest` is newer than `current`.
  * Uses Bun's built-in semver if available, falls back to simple comparison.
@@ -68,16 +94,27 @@ export function isNewerVersion(current: string, latest: string): boolean {
   if (typeof Bun !== "undefined" && Bun.semver) {
     return Bun.semver.order(current, latest) < 0;
   }
-  // Fallback: naive string comparison (works for simple semver; does not handle pre-release tags)
-  const curParts = current.split(".").map((s) => Number(s.split("-")[0]));
-  const newParts = latest.split(".").map((s) => Number(s.split("-")[0]));
+  // Fallback for Node/compiled binaries. npm orders `1.0.0-beta.1` BEFORE
+  // `1.0.0`, so a prerelease only counts as an upgrade when its numeric core
+  // is genuinely ahead — never for the same core, which would be a downgrade.
+  const curParts = semverParts(current);
+  const newParts = semverParts(latest);
+  let order = 0;
   for (let i = 0; i < Math.max(curParts.length, newParts.length); i++) {
     const c = curParts[i] ?? 0;
     const n = newParts[i] ?? 0;
-    if (n > c) return true;
-    if (n < c) return false;
+    if (n > c) {
+      order = 1;
+      break;
+    }
+    if (n < c) {
+      order = -1;
+      break;
+    }
   }
-  return false;
+  if (order !== 0) return order > 0;
+  // Same numeric core: only a prerelease -> release move is an upgrade.
+  return isPrerelease(current) && !isPrerelease(latest);
 }
 
 /**
@@ -257,6 +294,35 @@ export function recordPreUpdateState(currentVersion: string): void {
   });
 }
 
+/**
+ * Acknowledge that the post-upgrade panel for `shownVersion` has been seen.
+ *
+ * The panel's trigger is `lastInstalledVersion !== currentVersion`, so without
+ * this write the state stays "upgraded" forever and the panel reappears on
+ * every single launch — including after the user dismissed it with "later" or
+ * "never", since neither touches `lastInstalledVersion`. Writing the running
+ * version makes the condition false exactly once.
+ *
+ * Best-effort: a failed write must not block the panel from being shown.
+ */
+export function markPostUpgradeSeen(currentVersion: string): void {
+  try {
+    const state = readUpdateState();
+    // Already acknowledged — nothing to do.
+    if (state.lastInstalledVersion === currentVersion) return;
+    // Only acknowledge a recorded version that is genuinely OLDER than the
+    // running one (the upgrade we just showed notes for). If the recorded
+    // version is NEWER — e.g. an update landed mid-session, or the install was
+    // rolled back — leave it alone so the next launch still reports something.
+    if (isNewerVersion(currentVersion, state.lastInstalledVersion ?? "")) {
+      return;
+    }
+    writeUpdateState({ ...state, lastInstalledVersion: currentVersion });
+  } catch {
+    // non-critical
+  }
+}
+
 /**
  * Fetch release notes for a given version.
  * Tries release-notes/<version>.md first, then falls back to CHANGELOG.md section.