github-search-cli 9.8.3 → 9.10.0

package/dist/cli.js

@@ -24,11 +24,13 @@ var AuthError = class extends SearchCliError {
   }
 };
 var ForbiddenError = class extends SearchCliError {
-  constructor() {
-    const msg = "\u26A0 Forbidden (403). If your org enforces SSO, authorize the token; [t] to change it";
-    super("GitHub API returned 403 (token lacks access)", msg);
+  constructor(detail = "GitHub API returned 403") {
+    const msg = `\u26A0 Forbidden (403) \u2014 ${detail}. Common causes: org SSO not authorizing the token, or a secondary rate limit. Press [t] to change the token`;
+    super(msg, msg);
+    this.detail = detail;
     this.name = "ForbiddenError";
   }
+  detail;
 };
 var RateLimitError = class extends SearchCliError {
   constructor(hasToken, resetSeconds) {
@@ -39,16 +41,36 @@ var RateLimitError = class extends SearchCliError {
   }
   hasToken;
 };
+var BadQueryError = class extends SearchCliError {
+  /** A concrete, corrected query the user can retry with. */
+  constructor(detail, hint) {
+    super(
+      `Invalid query: ${detail}`,
+      hint ? `\u26A0 Invalid query: ${detail}
+  Try: ${hint}` : `\u26A0 Invalid query: ${detail}`
+    );
+    this.detail = detail;
+    this.hint = hint;
+    this.name = "BadQueryError";
+  }
+  detail;
+  hint;
+};
 var NoResultsError = class extends SearchCliError {
-  constructor(query) {
+  /** Concrete loosened queries to retry, most promising first. */
+  constructor(query, relaxations = []) {
+    const tips = relaxations.length ? relaxations.map((r) => `Try: ${r}`).join("\n  ") : "Tips: check spelling, try fewer qualifiers, or [b]rowse trending";
     super(
-      `No results for "${query}"`,
-      `\u{1F50D} No results for "${query}". Tips: check spelling, try fewer qualifiers, or [b]rowse trending`
+      relaxations.length > 0 ? `No results for "${query}" \u2014 try loosening: ${relaxations.join(" / ")}` : `No results for "${query}"`,
+      `\u{1F50D} No results for "${query}".
+  ${tips}`
     );
     this.query = query;
+    this.relaxations = relaxations;
     this.name = "NoResultsError";
   }
   query;
+  relaxations;
 };
 var ParseError = class extends SearchCliError {
   constructor(source, detail) {
@@ -209,9 +231,11 @@ function normalizeEnvelope(env) {
 var KNOWN_QUALIFIERS = [
   "language",
   "stars",
+  "forks",
   "fork",
   "archived",
   "topic",
+  "topics",
   "user",
   "org",
   "repo",
@@ -221,8 +245,80 @@ var KNOWN_QUALIFIERS = [
   "in",
   "size",
   "license",
-  "created"
+  "created",
+  "followers"
 ];
+var KNOWN_QUALIFIER_SET = new Set(KNOWN_QUALIFIERS);
+var QUALIFIER_ALIASES = {
+  // language
+  langauge: "language",
+  lang: "language",
+  languge: "language",
+  // stars / forks
+  star: "stars",
+  strs: "stars",
+  forke: "forks",
+  // topic
+  topc: "topic",
+  tpics: "topic",
+  // user / org
+  usr: "user",
+  ogranization: "org",
+  orginzation: "org",
+  // date qualifiers
+  push: "pushed",
+  creat: "created",
+  updat: "updated",
+  // visibility
+  visiblity: "visibility",
+  visability: "visibility",
+  // license
+  licence: "license",
+  // size
+  siz: "size",
+  // archived
+  archive: "archived"
+};
+function editDistanceWithin(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+      if (curr[j] < rowMin) rowMin = curr[j];
+    }
+    if (rowMin > max) return max + 1;
+    prev = curr;
+  }
+  return prev[b.length];
+}
+function resolveQualifierKey(key) {
+  const k = key.toLowerCase();
+  if (KNOWN_QUALIFIER_SET.has(k)) return k;
+  const alias = QUALIFIER_ALIASES[k];
+  if (alias) return alias;
+  if (k.length < 4) return k;
+  const maxDistance = k.length <= 5 ? 1 : 2;
+  let best;
+  let bestDistance = maxDistance + 1;
+  let ties = 0;
+  for (const known of KNOWN_QUALIFIERS) {
+    const d = editDistanceWithin(k, known, maxDistance);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = known;
+      ties = 1;
+      if (d === 0) break;
+    } else if (d === bestDistance && best !== void 0) {
+      ties++;
+    }
+  }
+  return best !== void 0 && ties === 1 ? best : k;
+}
 var QUALIFIER_SUGGESTIONS = {
   l: ["language:"],
   s: ["stars:", "size:"],
@@ -238,13 +334,164 @@ var QUALIFIER_SUGGESTIONS = {
   a: ["archived:"]
 };
 function suggestFor(input) {
-  const trimmed = input.trim().toLowerCase();
+  const trimmed = input.trim().toLowerCase().replace(/:$/, "");
   if (trimmed.length === 0) return [];
   if (trimmed.length === 1 && QUALIFIER_SUGGESTIONS[trimmed]) {
     return QUALIFIER_SUGGESTIONS[trimmed];
   }
-  const matches = KNOWN_QUALIFIERS.filter((k) => k.startsWith(trimmed));
-  return matches.map((k) => `${k}:`);
+  const resolved = resolveQualifierKey(trimmed);
+  const aliasHit = resolved !== trimmed && KNOWN_QUALIFIER_SET.has(resolved) ? [`${resolved}:`] : [];
+  const matches = KNOWN_QUALIFIERS.filter(
+    (k) => k.startsWith(trimmed) && !aliasHit.includes(`${k}:`)
+  ).map((k) => `${k}:`);
+  return [...aliasHit, ...matches];
+}
+var NUMERIC_QUALIFIERS = /* @__PURE__ */ new Set([
+  "forks",
+  "size",
+  "stars",
+  "topics",
+  "followers"
+]);
+var BOOLEAN_QUALIFIERS = /* @__PURE__ */ new Set(["archived"]);
+var VISIBILITY_VALUES = /* @__PURE__ */ new Set(["public", "private", "internal"]);
+var IN_FIELDS = /* @__PURE__ */ new Set([
+  "name",
+  "description",
+  "topics",
+  "readme",
+  "comments"
+]);
+var DATE_QUALIFIERS = /* @__PURE__ */ new Set(["created", "pushed", "updated"]);
+var COMPARISON_OPERATORS = [">=", "<=", ">", "<"];
+function redactToken(url, token) {
+  return token ? url.replace(token, "<token>") : url;
+}
+function splitComparison(value) {
+  for (const op of COMPARISON_OPERATORS) {
+    if (value.startsWith(op)) {
+      return { op, rest: value.slice(op.length) };
+    }
+  }
+  return { op: "", rest: value };
+}
+function parseCount(raw) {
+  const trimmed = raw.trim().replace(/_/g, "");
+  if (trimmed === "") return null;
+  const match = /^(\d+(?:\.\d+)?)([km])?$/i.exec(trimmed);
+  if (!match) return null;
+  if (!match[2] && match[1].includes(".")) return null;
+  const base = Number.parseFloat(match[1]);
+  if (!Number.isFinite(base)) return null;
+  const suffix = match[2]?.toLowerCase();
+  const multiplier = suffix === "k" ? 1e3 : suffix === "m" ? 1e6 : 1;
+  return Math.floor(base * multiplier);
+}
+function isValidISODate(raw) {
+  const trimmed = raw.trim();
+  const m = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?(?:Z|[+-]\d{2}:?\d{2})?)?$/.exec(
+    trimmed
+  );
+  if (!m) return false;
+  const [, y, mo, d, h = "0", mi = "0", s = "0"] = m;
+  const year = Number(y);
+  const month = Number(mo);
+  const day = Number(d);
+  if (month < 1 || month > 12) return false;
+  if (day < 1 || day > 31) return false;
+  if (Number(h) > 23 || Number(mi) > 59 || Number(s) > 59) return false;
+  const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+  return day <= daysInMonth;
+}
+function normalizeQualifierValue(key, value) {
+  const normalizedKey = key.toLowerCase();
+  if (!NUMERIC_QUALIFIERS.has(normalizedKey)) return value;
+  if (value === "") return value;
+  const { op, rest } = splitComparison(value);
+  const rangeIdx = rest.indexOf("..");
+  if (rangeIdx > 0) {
+    const lo = parseCount(rest.slice(0, rangeIdx));
+    const hi = parseCount(rest.slice(rangeIdx + 2));
+    if (lo === null || hi === null) return value;
+    return `${op}${lo}..${hi}`;
+  }
+  if (!/[km]$/i.test(rest.trim())) return value;
+  const count = parseCount(rest);
+  if (count === null) return value;
+  return `${op || ">="}${count}`;
+}
+function validateQualifierValue(key, value) {
+  const k = key.toLowerCase();
+  if (!KNOWN_QUALIFIER_SET.has(k)) return null;
+  if (value.trim() === "") {
+    return `"${key}:" needs a value (e.g. ${key}:<something>)`;
+  }
+  if (NUMERIC_QUALIFIERS.has(k)) {
+    const { rest } = splitComparison(value.trim());
+    const rangeIdx = rest.indexOf("..");
+    if (rangeIdx > 0) {
+      const lo = parseCount(rest.slice(0, rangeIdx));
+      const hi = parseCount(rest.slice(rangeIdx + 2));
+      if (lo === null || hi === null) {
+        return `"${key}:${value}" is not a valid range \u2014 use ${k}:100..500 or ${k}:>=100`;
+      }
+      if (lo > hi) {
+        return `"${key}:${value}" has a reversed range (${lo} > ${hi})`;
+      }
+      return null;
+    }
+    if (parseCount(rest) === null) {
+      return `"${key}:${value}" is not a number \u2014 use ${k}:100, ${k}:>=100, or ${k}:1k..10k`;
+    }
+    return null;
+  }
+  if (k === "fork") {
+    const v = value.trim().toLowerCase();
+    if (v !== "true" && v !== "false" && v !== "only") {
+      return `"fork:${value}" is not valid \u2014 use fork:true, fork:false, or fork:only`;
+    }
+    return null;
+  }
+  if (BOOLEAN_QUALIFIERS.has(k)) {
+    const v = value.trim().toLowerCase();
+    if (v !== "true" && v !== "false") {
+      return `"${key}:${value}" is not valid \u2014 use ${k}:true or ${k}:false`;
+    }
+    return null;
+  }
+  if (k === "visibility") {
+    const v = value.trim().toLowerCase();
+    if (!VISIBILITY_VALUES.has(v)) {
+      return `"visibility:${value}" is not valid \u2014 use visibility:public, visibility:private, or visibility:internal`;
+    }
+    return null;
+  }
+  if (k === "in") {
+    const parts = value.split(",").map((p) => p.trim().toLowerCase());
+    if (parts.some((p) => !IN_FIELDS.has(p))) {
+      const bad = parts.find((p) => !IN_FIELDS.has(p));
+      return `"in:${value}" is not valid \u2014 ${bad ? `"${bad}" is not a ` : ""}searchable field. Try in:name, in:description, in:topics, or in:readme`;
+    }
+    return null;
+  }
+  if (DATE_QUALIFIERS.has(k)) {
+    const trimmed = value.trim();
+    const { rest } = splitComparison(trimmed);
+    const rangeIdx = rest.indexOf("..");
+    if (rangeIdx > 0) {
+      const lo = rest.slice(0, rangeIdx);
+      const hi = rest.slice(rangeIdx + 2);
+      if (!isValidISODate(lo) || !isValidISODate(hi)) {
+        return `"${key}:${value}" is not a valid date range \u2014 use ${k}:2020-01-01..2024-01-01`;
+      }
+      return null;
+    }
+    if (!isValidISODate(rest)) {
+      return `"${key}:${value}" is not a valid date \u2014 use ${k}:2024-01-01 (optionally with >, >=, <, <=)`;
+    }
+    return null;
+  }
+  return null;
 }
 function tokenize(input) {
   const tokens = [];
@@ -272,22 +519,46 @@ function tokenize(input) {
   }
   return tokens;
 }
+var EMPTY_QUERY = {
+  keywords: [],
+  qualifiers: [],
+  raw: "",
+  corrections: []
+};
+function trendingQuery() {
+  return { ...EMPTY_QUERY, raw: "trending" };
+}
 function parseQuery(raw) {
   const trimmed = raw.trim();
   if (trimmed === "") {
-    return { keywords: [], qualifiers: [], raw };
+    return { keywords: [], qualifiers: [], raw, corrections: [] };
   }
   const keywords = [];
   const qualifiers = [];
+  const corrections = [];
   for (const token of tokenize(trimmed)) {
     const qualifier = matchQualifier(token);
     if (qualifier) {
-      qualifiers.push(qualifier);
+      const resolvedKey = resolveQualifierKey(qualifier.key);
+      const normalizedValue = normalizeQualifierValue(
+        resolvedKey,
+        qualifier.value
+      );
+      const original = `${qualifier.negated ? "-" : ""}${qualifier.key}:${qualifier.value}`;
+      const corrected = `${qualifier.negated ? "-" : ""}${resolvedKey}:${normalizedValue}`;
+      if (original !== corrected) {
+        corrections.push({ from: original, to: corrected });
+      }
+      qualifiers.push({
+        key: resolvedKey,
+        value: normalizedValue,
+        negated: qualifier.negated
+      });
     } else {
       keywords.push(token);
     }
   }
-  return { keywords, qualifiers, raw: trimmed };
+  return { keywords, qualifiers, raw: trimmed, corrections };
 }
 function matchQualifier(token) {
   const negated = token.startsWith("-");
@@ -296,8 +567,7 @@ function matchQualifier(token) {
   if (idx <= 0) return null;
   const key = body.slice(0, idx).toLowerCase();
   let value = body.slice(idx + 1);
-  if (value === "") return null;
-  if (!/^[a-z]+$/i.test(key)) return null;
+  if (!/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/i.test(key)) return null;
   if (value.startsWith("//")) return null;
   if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
     value = value.slice(1, -1);
@@ -330,11 +600,143 @@ function applyFlagFilters(query, flags) {
     });
   return { ...query, qualifiers };
 }
+function withoutQualifier(query, index) {
+  const remaining = query.qualifiers.filter((_, i) => i !== index);
+  const parts = [...query.keywords];
+  for (const q of remaining) {
+    const needsQuote = q.value.includes(" ") && !q.value.startsWith('"');
+    const value = needsQuote ? `"${q.value}"` : q.value;
+    parts.push(`${q.negated ? "-" : ""}${q.key}:${value}`);
+  }
+  const text = parts.join(" ").trim();
+  return text === "" ? null : text;
+}
 function validateQuery(query) {
   const has = (key) => query.qualifiers.some((q) => q.key === key && !q.negated);
   if (has("visibility") && has("private")) {
-    throw new Error("Cannot combine `visibility:` and `private:` filters.");
+    throw new BadQueryError(
+      "Cannot combine `visibility:` and `private:` filters.",
+      `${query.qualifiers.filter((q) => q.key === "private" && !q.negated).map((q) => withoutQualifier(query, query.qualifiers.indexOf(q))).find((v) => v !== null) ?? query.raw}`
+    );
+  }
+  for (let i = 0; i < query.qualifiers.length; i++) {
+    const q = query.qualifiers[i];
+    const problem = validateQualifierValue(q.key, q.value);
+    if (problem) {
+      throw new BadQueryError(problem, withoutQualifier(query, i) ?? void 0);
+    }
+  }
+}
+var OVER_CONSTRAINT_WEIGHT = {
+  size: 100,
+  stars: 95,
+  forks: 80,
+  created: 75,
+  pushed: 70,
+  updated: 70,
+  visibility: 65,
+  repo: 60,
+  user: 55,
+  org: 50,
+  topic: 45,
+  in: 30,
+  license: 25,
+  language: 20,
+  fork: 15,
+  archived: 10
+};
+function loosenNumericBound(value) {
+  const { op, rest } = splitComparison(value.trim());
+  const count = parseCount(rest);
+  if (count === null || count === 0) return null;
+  const loosened = Math.max(1, Math.floor(count / 10));
+  return `${op || ">="}${loosened}`;
+}
+function loosenDateBound(value) {
+  const { op, rest } = splitComparison(value.trim());
+  if (!isValidISODate(rest)) return null;
+  const year = Number.parseInt(rest.slice(0, 4), 10);
+  if (!Number.isFinite(year)) return null;
+  const shifted = op === "<" || op === "<=" ? year + 2 : Math.max(1970, year - 2);
+  return { op, date: `${shifted}${rest.slice(4)}` };
+}
+function suggestRelaxations(query, limit = 3) {
+  const out = [];
+  for (let i = 0; i < query.qualifiers.length; i++) {
+    const q = query.qualifiers[i];
+    const key = q.key.toLowerCase();
+    if (q.negated) continue;
+    const weight = OVER_CONSTRAINT_WEIGHT[key] ?? 40;
+    const emit = (relaxed, qualifier) => {
+      const rest = query.qualifiers.filter((_, j) => j !== i).map((other) => {
+        const needsQuote = other.value.includes(" ") && !other.value.startsWith('"');
+        const value = needsQuote ? `"${other.value}"` : other.value;
+        return `${other.negated ? "-" : ""}${other.key}:${value}`;
+      });
+      const text = [...query.keywords, ...rest, relaxed].join(" ").trim();
+      out.push({ suggestion: text, qualifier, confidence: weight });
+    };
+    if (NUMERIC_QUALIFIERS.has(key) || key === "followers") {
+      const rangeIdx = q.value.indexOf("..");
+      if (rangeIdx > 0) {
+        const hi = parseCount(q.value.slice(rangeIdx + 2));
+        if (hi !== null) {
+          const lo = q.value.slice(0, rangeIdx);
+          emit(`${key}:${lo}..${Math.floor(hi / 10) || hi * 2}`, key);
+        }
+      } else {
+        const looser = loosenNumericBound(q.value);
+        if (looser) emit(`${key}:${looser}`, key);
+        else {
+          const dropped2 = withoutQualifier(query, i);
+          if (dropped2) {
+            out.push({
+              suggestion: dropped2,
+              qualifier: key,
+              confidence: weight - 30
+            });
+          }
+        }
+      }
+      continue;
+    }
+    if (DATE_QUALIFIERS.has(key)) {
+      const loosened = loosenDateBound(q.value);
+      if (loosened) {
+        emit(`${key}:${loosened.op || ">="}${loosened.date}`, key);
+      } else {
+        const dropped2 = withoutQualifier(query, i);
+        if (dropped2) {
+          out.push({
+            suggestion: dropped2,
+            qualifier: key,
+            confidence: weight - 30
+          });
+        }
+      }
+      continue;
+    }
+    const dropped = withoutQualifier(query, i);
+    if (dropped) {
+      out.push({
+        suggestion: dropped,
+        qualifier: key,
+        confidence: weight - 30
+      });
+    }
   }
+  const seen = /* @__PURE__ */ new Set();
+  const unique = out.filter((r) => {
+    if (seen.has(r.suggestion)) return false;
+    seen.add(r.suggestion);
+    return true;
+  });
+  unique.sort((a, b) => b.confidence - a.confidence);
+  return unique.slice(0, limit).map((r) => ({
+    ...r,
+    // Clamp so a "drop the qualifier" hint never reports a negative score.
+    confidence: Math.max(0, r.confidence)
+  }));
 }
 function buildGitHubQuery(query) {
   const parts = [];
@@ -431,6 +833,11 @@ var GitHubSearchAdapter = class {
           });
           const remainingStr = res.headers.get("x-ratelimit-remaining");
           rateLimitRemaining = remainingStr !== null ? Number(remainingStr) : void 0;
+          if (process.env.GHFIND_LOG) {
+            this.logger.debug(
+              `[github] ${res.status} remaining=${remainingStr ?? "none"} url=${redactToken(pagedUrl, token)}`
+            );
+          }
           if (res.status === 403) {
             if (remainingStr === "0" || remainingStr === null) {
               if (this.tokens.length > 0 && attempt < this.tokens.length) {
@@ -442,9 +849,18 @@ var GitHubSearchAdapter = class {
             }
             const body = await res.text().catch(() => "");
             this.logger.error(
-              `[github] non-rate-limit 403: ${body.slice(0, 200)}`
+              `[github] non-rate-limit 403: remaining=${remainingStr} retry-after=${res.headers.get("retry-after") ?? "none"} x-ratelimit-reset=${res.headers.get("x-ratelimit-reset") ?? "none"} authed=${token ? "yes" : "no"} url=${redactToken(pagedUrl, token)}`
             );
-            throw new ForbiddenError();
+            this.logger.error(`[github] 403 body: ${body.slice(0, 400)}`);
+            let reason = "no reason given";
+            try {
+              const parsed2 = JSON.parse(body);
+              if (typeof parsed2.message === "string" && parsed2.message) {
+                reason = parsed2.message;
+              }
+            } catch {
+            }
+            throw new ForbiddenError(reason);
           }
           if (res.status === 401) {
             const body = await res.text().catch(() => "");
@@ -1737,7 +2153,7 @@ var cached = null;
 function getVersion() {
   if (cached) return cached;
   if (true) {
-    cached = "9.8.3";
+    cached = "9.10.0";
     return cached;
   }
   try {
@@ -1996,22 +2412,22 @@ async function runWatch(opts, onChange, onError) {
   let previous = [];
   let failCount = 0;
   let intervalId = null;
+  if (!opts.trending) {
+    validateQuery(applyFlagFilters(parseQuery(opts.query), {}));
+  }
   const tick = async () => {
     try {
       let repos;
       if (opts.trending) {
         const since = opts.query === "weekly" ? "weekly" : opts.query === "monthly" ? "monthly" : "daily";
         const trendingSearch = createTrendingSearch();
-        const response = await trendingSearch.search(
-          { keywords: [], qualifiers: [], raw: "trending" },
-          {
-            limit: opts.limit,
-            sort: opts.sort,
-            json: false,
-            verbose: false,
-            trendingSince: since
-          }
-        );
+        const response = await trendingSearch.search(trendingQuery(), {
+          limit: opts.limit,
+          sort: opts.sort,
+          json: false,
+          verbose: false,
+          trendingSince: since
+        });
         repos = response.repos;
       } else {
         const parsed = applyFlagFilters(parseQuery(opts.query), {});
@@ -3422,6 +3838,7 @@ import {
   SelectRenderable,
   ScrollBoxRenderable as ScrollBoxRenderable3
 } from "@opentui/core";
+import { appendFileSync as appendFileSync2 } from "fs";
 
 // src/trending.ts
 import {
@@ -3457,6 +3874,135 @@ if (import.meta.main && false) {
   launchTrending();
 }
 
+// src/tui/mouse.ts
+var DOUBLE_CLICK_MS = 400;
+function hitIndexForY(geometry, screenY) {
+  const pitch = geometry.linesPerItem;
+  if (pitch <= 0) return -1;
+  if (geometry.optionCount <= 0) return -1;
+  const localY = screenY - geometry.screenY;
+  if (localY < 0 || localY >= geometry.height) return -1;
+  const row = Math.floor(localY / pitch);
+  const index = geometry.scrollOffset + row;
+  const last = geometry.optionCount - 1;
+  if (index < 0) return 0;
+  return index > last ? last : index;
+}
+function selectRowGeometry(select) {
+  const internal = select;
+  return {
+    screenY: select.screenY,
+    height: select.height,
+    optionCount: select.options.length,
+    scrollOffset: internal.scrollOffset ?? 0,
+    linesPerItem: internal.linesPerItem ?? 0
+  };
+}
+function attachClickToSelect(renderer, select, options = {}) {
+  const wheelStep = options.wheelStep ?? 3;
+  let lastClickIndex = -1;
+  let lastClickAt = 0;
+  let lastHovered = -1;
+  select.onMouseDown = (event) => {
+    event.stopPropagation();
+    if (options.keepFocus) event.preventDefault();
+    const index = hitIndexForY(selectRowGeometry(select), event.y);
+    if (index < 0) {
+      lastClickIndex = -1;
+      options.onClickMiss?.();
+      return;
+    }
+    const now = Date.now();
+    const alreadySelected = select.getSelectedIndex() === index;
+    const isDouble = alreadySelected && index === lastClickIndex && now - lastClickAt < DOUBLE_CLICK_MS;
+    lastClickIndex = index;
+    lastClickAt = now;
+    if (isDouble) {
+      lastClickIndex = -1;
+      options.onOpen?.();
+      return;
+    }
+    select.setSelectedIndex(index);
+  };
+  select.onMouseScroll = (event) => {
+    event.stopPropagation();
+    const direction = event.scroll?.direction;
+    if (direction === "up") select.moveUp(wheelStep);
+    else if (direction === "down") select.moveDown(wheelStep);
+    else return;
+    renderer.requestRender();
+  };
+  attachHoverHighlight(renderer, select, {
+    onHover: (index) => {
+      lastHovered = index;
+      options.onHoverRow?.(index);
+    },
+    // A stale row must never outlive the options it pointed at.
+    onLeave: () => {
+      lastHovered = -1;
+    }
+  });
+  return {
+    reset() {
+      lastClickIndex = -1;
+      lastClickAt = 0;
+    },
+    get lastHovered() {
+      return lastHovered;
+    }
+  };
+}
+function attachHoverHighlight(renderer, select, options = {}) {
+  const idleBackground = select.backgroundColor;
+  const hoverBackground = "#ffffff0f";
+  let hovered = -1;
+  select.onMouseOver = () => {
+    renderer.setMousePointer("pointer");
+    select.backgroundColor = hoverBackground;
+    renderer.requestRender();
+  };
+  select.onMouseOut = () => {
+    renderer.setMousePointer("default");
+    select.backgroundColor = idleBackground;
+    if (hovered !== -1) {
+      hovered = -1;
+      options.onLeave?.();
+    }
+    renderer.requestRender();
+  };
+  select.onMouseMove = (event) => {
+    const index = hitIndexForY(selectRowGeometry(select), event.y);
+    if (index === hovered) return;
+    hovered = index;
+    options.onHover?.(index);
+  };
+}
+function attachClickOutside(target, onDismiss) {
+  target.onMouseDown = (event) => {
+    event.stopPropagation();
+    onDismiss();
+  };
+}
+function attachClickableBox(renderer, box, handlers) {
+  box.onMouseDown = (event) => {
+    event.stopPropagation();
+    handlers.onActivate();
+  };
+  box.onMouseOver = () => {
+    renderer.setMousePointer("pointer");
+    box.borderColor = handlers.activeBorder;
+    handlers.onStateChange?.();
+    renderer.requestRender();
+  };
+  box.onMouseOut = () => {
+    renderer.setMousePointer("default");
+    box.borderColor = handlers.idleBorder;
+    handlers.onStateChange?.();
+    renderer.requestRender();
+  };
+}
+var NON_INTERACTIVE_TEXT = { selectable: false };
+
 // src/help.ts
 function buildHelpSections() {
   return [
@@ -3478,7 +4024,7 @@ function buildHelpSections() {
         { keys: "\u2191 \u2193 / 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" }
       ]
@@ -3512,7 +4058,8 @@ function buildHelpSections() {
       rows: [
         { keys: "1-5", action: "Switch tab: Today \u2192 Week \u2192 Month \u2192 \u2026" },
         { keys: "\u2190 \u2192 / h l", action: "Navigate tabs" }
-      ]
+      ],
+      note: "Tabs are also clickable."
     },
     {
       title: " Packages Mode ",
@@ -3521,12 +4068,12 @@ function buildHelpSections() {
         { keys: "/", action: "Search npm packages" },
         { keys: "\u2191 \u2193 / 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 \u2192 stars \u2192 \u2026" },
@@ -3551,7 +4098,7 @@ function buildHelpSections() {
         { keys: "History", action: "View search history" },
         { keys: "Help", action: "Show this help screen" }
       ],
-      note: "Navigate menu with \u2191 \u2193, select with Enter, back with \u2190 / Esc"
+      note: "Navigate menu with \u2191 \u2193, select with Enter, back with \u2190 / Esc. Clicking a row runs it directly. Esc (or the \u2630 menu button) opens this menu; Space types a space in the query."
     },
     {
       title: " Bookmarks Page ",
@@ -3564,6 +4111,22 @@ function buildHelpSections() {
       ],
       note: "A full page, not an overlay \u2014 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: "\u2630 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",
@@ -4455,19 +5018,40 @@ function shouldCheckUpdate() {
   if (Date.now() - state.lastCheck < CHECK_INTERVAL_MS) return false;
   return true;
 }
+function semverParts(v) {
+  const core = v.trim().replace(/^v/i, "").split(/[-+]/)[0];
+  return core.split(".").map((s) => {
+    const n = Number(s);
+    return Number.isFinite(n) ? n : 0;
+  });
+}
+function isPrerelease(v) {
+  const core = v.trim().replace(/^v/i, "");
+  const plus = core.indexOf("+");
+  const coreOnly = plus === -1 ? core : core.slice(0, plus);
+  return coreOnly.includes("-");
+}
 function isNewerVersion(current, latest) {
   if (typeof Bun !== "undefined" && Bun.semver) {
     return Bun.semver.order(current, latest) < 0;
   }
-  const curParts = current.split(".").map((s) => Number(s.split("-")[0]));
-  const newParts = latest.split(".").map((s) => Number(s.split("-")[0]));
+  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;
+  return isPrerelease(current) && !isPrerelease(latest);
 }
 async function checkForUpdate(currentVersion) {
   if (process.env.DEBUG)
@@ -4574,6 +5158,17 @@ function recordPreUpdateState(currentVersion) {
     lastInstalledVersion: currentVersion
   });
 }
+function markPostUpgradeSeen(currentVersion) {
+  try {
+    const state = readUpdateState();
+    if (state.lastInstalledVersion === currentVersion) return;
+    if (isNewerVersion(currentVersion, state.lastInstalledVersion ?? "")) {
+      return;
+    }
+    writeUpdateState({ ...state, lastInstalledVersion: currentVersion });
+  } catch {
+  }
+}
 function fetchReleaseNotes(version) {
   try {
     const notesPath = join6(PKG_DIR2, "release-notes", `${version}.md`);
@@ -4648,16 +5243,33 @@ var colors = {
   surfaceDim: "#1a1919",
   borderAccent: "#1a1919"
 };
-var logger = {
-  debug: () => {
-  },
-  info: () => {
-  },
-  warn: () => {
-  },
-  error: () => {
-  }
-};
+function createTuiLogger() {
+  const target = process.env.GHFIND_LOG;
+  if (!target) {
+    return { debug: () => {
+    }, info: () => {
+    }, warn: () => {
+    }, error: () => {
+    } };
+  }
+  const write = (level, msg) => {
+    try {
+      appendFileSync2(
+        target,
+        `[${(/* @__PURE__ */ new Date()).toISOString()}] [${level}] ${msg}
+`
+      );
+    } catch {
+    }
+  };
+  return {
+    debug: (m) => write("debug", m),
+    info: (m) => write("info", m),
+    warn: (m) => write("warn", m),
+    error: (m) => write("error", m)
+  };
+}
+var logger = createTuiLogger();
 var SORT_MODES = [
   { key: "best-match", label: "best-match" },
   { key: "stars", label: "stars" },
@@ -4731,7 +5343,7 @@ async function launchBrowser(theme_override) {
   const compareList = [];
   const _quitArmed = false;
   const header = new TextRenderable5(renderer, {
-    content: " ghfind \u2014 GitHub repo browser   [/]search  [Space]menu  [\u2192]open  [?]help  [q]uit",
+    content: " ghfind \u2014 GitHub repo browser   [/]search  [Esc]menu  [\u2192]open  [?]help  [q]uit   \xB7   click select \xB7 dbl-click open",
     bg: colors.bg,
     fg: colors.muted,
     height: 1
@@ -4752,15 +5364,25 @@ async function launchBrowser(theme_override) {
       const isActive = name === trendingTab;
       const label = ` ${name} `;
       const tt = new TextRenderable5(renderer, {
+        ...NON_INTERACTIVE_TEXT,
         content: label,
         fg: isActive ? colors.bg : colors.muted,
         bg: isActive ? colors.blue : colors.bg,
         height: 1
       });
+      tt.onMouseDown = (event) => {
+        event.stopPropagation();
+        if (name === trendingTab) return;
+        trendingTab = name;
+        loadTrending();
+      };
+      tt.onMouseOver = () => renderer.setMousePointer("pointer");
+      tt.onMouseOut = () => renderer.setMousePointer("default");
       trendingTabTexts.push(tt);
       trendingTabBox.add(tt);
       if (i < TAB_NAMES.length - 1) {
         const sp = new TextRenderable5(renderer, {
+          ...NON_INTERACTIVE_TEXT,
           content: "  ",
           fg: colors.muted,
           bg: colors.bg,
@@ -4848,7 +5470,10 @@ async function launchBrowser(theme_override) {
   const detailText = new TextRenderable5(renderer, {
     content: "",
     fg: colors.text,
-    wrapMode: "none"
+    wrapMode: "none",
+    // Non-interactive: a left-press here would otherwise be swallowed as a
+    // text-selection drag instead of reaching the click handlers.
+    selectable: false
   });
   detailBox.add(detailText);
   body.add(resultsBox);
@@ -4863,6 +5488,7 @@ async function launchBrowser(theme_override) {
   });
   root.add(landingBox);
   const landingBanner = new TextRenderable5(renderer, {
+    ...NON_INTERACTIVE_TEXT,
     content: [
       " \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ",
       "\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557",
@@ -4940,7 +5566,8 @@ async function launchBrowser(theme_override) {
     card.add(spacerBot);
   }
   const landingHint = new TextRenderable5(renderer, {
-    content: "   \u2191\u2193 Navigate  \u21E9 Select  [b]ookmarks  [?]help  [q]uit",
+    ...NON_INTERACTIVE_TEXT,
+    content: "   \u2191\u2193 Navigate  \u21E9 Select  [b]ookmarks  [?]help  [q]uit   \xB7   click to pick a mode",
     fg: colors.muted,
     bg: colors.bg,
     height: 1,
@@ -4968,6 +5595,28 @@ async function launchBrowser(theme_override) {
       }
     }
   }
+  landingCards.forEach((card, i) => {
+    let lastClickAt = 0;
+    card.onMouseDown = (event) => {
+      event.stopPropagation();
+      const now = Date.now();
+      const isDouble = landingSelected === i && now - lastClickAt < DOUBLE_CLICK_MS;
+      lastClickAt = now;
+      if (isDouble) {
+        landingOptions[i].action();
+        return;
+      }
+      landingSelected = i;
+      updateLandingCards();
+      renderer.requestRender();
+    };
+    card.onMouseOver = () => {
+      renderer.setMousePointer("pointer");
+    };
+    card.onMouseOut = () => {
+      renderer.setMousePointer("default");
+    };
+  });
   renderer.keyInput.on("keypress", (key) => {
     if (!landingKeysActive(currentMode, currentOverlay)) return;
     if (key.name === "up" || key.name === "k") {
@@ -5032,6 +5681,7 @@ async function launchBrowser(theme_override) {
     updateDim.visible = false;
     if (type === "none") {
       currentOverlay = "none";
+      menuButton.visible = true;
       if (currentMode === "landing") {
         landingBox.visible = true;
         body.visible = false;
@@ -5045,6 +5695,7 @@ async function launchBrowser(theme_override) {
       return;
     }
     currentOverlay = type;
+    menuButton.visible = false;
     landingBox.visible = false;
     if (type !== "leader") {
       hideMainContent();
@@ -5306,7 +5957,8 @@ async function launchBrowser(theme_override) {
   const compareText = new TextRenderable5(renderer, {
     content: "",
     fg: colors.text,
-    bg: colors.bg
+    bg: colors.bg,
+    selectable: false
   });
   compareBox.add(compareText);
   root.add(compareBox);
@@ -5435,7 +6087,8 @@ async function launchBrowser(theme_override) {
     itemSpacing: 0
   });
   const leaderFooter = new TextRenderable5(renderer, {
-    content: " \u2191\u2193 select   Enter run   Esc/q close ",
+    ...NON_INTERACTIVE_TEXT,
+    content: " \u2191\u2193 select   Enter run   Esc/q close   \xB7   click to run   click outside to close ",
     fg: colors.muted,
     bg: colors.surfaceDim,
     height: 1,
@@ -5567,10 +6220,59 @@ async function launchBrowser(theme_override) {
     neverText.fg = updateSelectedOption === 2 ? colors.yellow : colors.text;
     renderer.requestRender();
   }
+  function runUpdateOption(index) {
+    updateSelectedOption = index;
+    renderUpdateOptions();
+    const action = ["now", "later", "never"][index];
+    if (action === "now") {
+      showOverlay("none");
+      recordPreUpdateState(cachedVersion ?? "");
+      performUpdate().then((ok) => {
+        if (ok) {
+          setStatus("\u2713 Update complete \u2014 restart ghfind");
+        } else {
+          setStatus("\u2717 Update failed \u2014 check terminal output");
+        }
+      }).catch(() => {
+        setStatus("\u2717 Update failed \u2014 check terminal output");
+      });
+    } else if (action === "never") {
+      suppressUpdateNotices();
+      showOverlay("none");
+      setStatus("Update notices suppressed");
+    } else {
+      snoozeUpdateNotices(3);
+      showOverlay("none");
+      setStatus("Update reminder snoozed for 3 days");
+    }
+    renderer.requestRender();
+  }
+  const updateCards = [
+    [updateNowBox, 0],
+    [laterBox, 1],
+    [neverBox, 2]
+  ];
+  for (const [box, index] of updateCards) {
+    attachClickableBox(renderer, box, {
+      onActivate: () => runUpdateOption(index),
+      idleBorder: updateSelectedOption === index ? colors.yellow : colors.border,
+      activeBorder: colors.yellow,
+      // Hovering must not fight the selection highlight, so it only moves the
+      // pointer cursor; the border stays owned by renderUpdateOptions().
+      onStateChange: () => {
+        box.borderColor = updateSelectedOption === index ? colors.yellow : colors.border;
+      }
+    });
+  }
+  attachClickOutside(updateDim, () => {
+    showOverlay("none");
+    renderer.requestRender();
+  });
   updateOptionsRow.add(updateNowBox);
   updateOptionsRow.add(laterBox);
   const updateFooter = new TextRenderable5(renderer, {
-    content: "  \u2191\u2193/jk/PgUp/PgDn scroll  \u2190\u2192 select  Enter  Esc/q close",
+    ...NON_INTERACTIVE_TEXT,
+    content: "  \u2191\u2193/jk/PgUp/PgDn scroll  \u2190\u2192 select  Enter  Esc/q close  \xB7  click a button  click outside to close",
     fg: colors.muted,
     bg: colors.surfaceDim,
     height: 1,
@@ -5926,6 +6628,7 @@ async function launchBrowser(theme_override) {
     if (!state.lastInstalledVersion) return;
     if (state.lastInstalledVersion === currentVersion) return;
     const notes = fetchReleaseNotes(currentVersion);
+    markPostUpgradeSeen(currentVersion);
     updateSelectedOption = 0;
     updateHeader.content = `  Updated ghfind ${state.lastInstalledVersion} \u2192 ${currentVersion}
 `;
@@ -6204,6 +6907,40 @@ async function launchBrowser(theme_override) {
     paddingX: 1
   });
   root.add(statusBar);
+  const menuButton = new BoxRenderable5(renderer, {
+    position: "absolute",
+    bottom: 1,
+    right: 1,
+    height: 1,
+    paddingX: 1,
+    backgroundColor: colors.surface,
+    focusable: false
+  });
+  const menuButtonLabel = new TextRenderable5(renderer, {
+    ...NON_INTERACTIVE_TEXT,
+    content: "\u2630 menu",
+    fg: colors.muted,
+    bg: colors.surface,
+    height: 1
+  });
+  menuButton.add(menuButtonLabel);
+  root.add(menuButton);
+  menuButton.onMouseDown = (event) => {
+    event.stopPropagation();
+    if (currentOverlay === "leader") showOverlay("none");
+    else showLeaderMenu();
+    renderer.requestRender();
+  };
+  menuButton.onMouseOver = () => {
+    renderer.setMousePointer("pointer");
+    menuButtonLabel.fg = colors.accent;
+    renderer.requestRender();
+  };
+  menuButton.onMouseOut = () => {
+    renderer.setMousePointer("default");
+    menuButtonLabel.fg = colors.muted;
+    renderer.requestRender();
+  };
   const statusMgr = new StatusManager((text) => {
     statusBar.content = ` ${text}`;
     renderer.requestRender();
@@ -6522,16 +7259,13 @@ async function launchBrowser(theme_override) {
     renderer.requestRender();
     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 = since === "daily" ? "today" : since === "weekly" ? "this week" : "this month";
@@ -6671,7 +7405,10 @@ async function launchBrowser(theme_override) {
         currentRepos = newRepos;
       }
       if (currentRepos.length === 0) {
-        throw new NoResultsError(q);
+        throw new NoResultsError(
+          q,
+          suggestRelaxations(parsed).map((r) => r.suggestion)
+        );
       } else {
         resultsSelect.options = currentRepos.map((r) => ({
           name: formatResultLine(r),
@@ -6797,6 +7534,158 @@ ${pack.description ?? ""}`;
       if (repo) openUrl(repo.url);
     }
   });
+  attachClickToSelect(renderer, resultsSelect, {
+    keepFocus: true,
+    onOpen: () => resultsSelect.selectCurrent()
+  });
+  function activateOverlaySelection() {
+    switch (currentOverlay) {
+      case "history": {
+        const sel = historySelect.getSelectedOption();
+        if (sel?.value) {
+          const entry = sel.value.entry;
+          showOverlay("none");
+          if (!entry) return;
+          if (entry.mode === "trending") {
+            if (entry.tab)
+              trendingTab = entry.tab;
+            loadTrending();
+          } else {
+            searchInput.value = entry.query;
+            showSearchMode();
+            doSearch(entry.query);
+          }
+        }
+        return;
+      }
+      case "bookmarks": {
+        const sel = bookmarksSelect.getSelectedOption();
+        if (sel?.value)
+          openUrl(sel.value.repo?.url ?? "");
+        return;
+      }
+      case "saved": {
+        const sel = savedSelect.getSelectedOption();
+        if (sel?.value) {
+          const s = sel.value;
+          showOverlay("none");
+          touchSavedSearch(s.name);
+          if (s.mode === "trending") {
+            if (s.tab) trendingTab = s.tab;
+            loadTrending();
+          } else {
+            searchInput.value = s.query;
+            showSearchMode();
+            currentSort = s.sort;
+            currentLimit = s.limit;
+            setToolbar();
+            doSearch(s.query);
+          }
+        }
+        return;
+      }
+      case "topics": {
+        const sel = topicsSelect.getSelectedOption();
+        if (sel?.value) {
+          const topic = sel.value;
+          showOverlay("none");
+          searchInput.value = `topic:${topic.name ?? ""}`;
+          showSearchMode();
+          doSearch(`topic:${topic.name}`);
+        }
+        return;
+      }
+      case "export": {
+        const sel = exportSelect.getSelectedOption();
+        if (sel?.value && currentRepos.length > 0) {
+          const format2 = sel.value;
+          const path = exportToFile(currentRepos, format2);
+          showOverlay("none");
+          setStatus(`\u2713 Exported to ${path}`);
+        } else {
+          setStatus("No results to export");
+          showOverlay("none");
+        }
+        renderer.requestRender();
+        return;
+      }
+      case "share": {
+        const sel = shareSelect.getSelectedOption();
+        if (sel?.value) {
+          const opt = resultsSelect.getSelectedOption();
+          const repo = opt?.value;
+          if (repo) {
+            const text = formatShare(repo, sel.value);
+            copyToClipboard(text).then((ok) => {
+              showOverlay("none");
+              setStatus(ok ? "\u2713 Copied!" : "Clipboard not available");
+            });
+          }
+        }
+        renderer.requestRender();
+        return;
+      }
+      case "help": {
+        showOverlay("none");
+        renderer.requestRender();
+        return;
+      }
+      default:
+        return;
+    }
+  }
+  function attachOverlayMouse(box, select) {
+    attachClickToSelect(renderer, select, {
+      onOpen: () => activateOverlaySelection(),
+      onClickMiss: () => {
+        showOverlay("none");
+        renderer.requestRender();
+      }
+    });
+    attachClickOutside(box, () => {
+      showOverlay("none");
+      renderer.requestRender();
+    });
+  }
+  attachOverlayMouse(historyBox, historySelect);
+  attachOverlayMouse(bookmarksBox, bookmarksSelect);
+  attachOverlayMouse(savedBox, savedSelect);
+  attachOverlayMouse(topicsBox, topicsSelect);
+  attachOverlayMouse(exportBox, exportSelect);
+  attachOverlayMouse(shareBox, shareSelect);
+  for (const panel of [helpBox, orgBox, readmeBox, compareBox, notifsBox]) {
+    attachClickOutside(panel, () => {
+      showOverlay("none");
+      renderer.requestRender();
+    });
+  }
+  for (const scroller of [helpScroll, orgScroll, readmeScroll, updateScroll]) {
+    scroller.onMouseScroll = (event) => {
+      event.stopPropagation();
+    };
+  }
+  attachClickToSelect(renderer, leaderSelect, {
+    onOpen: () => {
+      const entry = leaderSelect.getSelectedOption()?.value;
+      if (!entry) return;
+      if (entry.type === "category") {
+        pushMenuLevel(`  Menu > ${entry.name}`, entry.name, entry.children, 0);
+      } else {
+        resetMenu();
+        showOverlay("none");
+        entry.action();
+      }
+      renderer.requestRender();
+    },
+    onClickMiss: () => {
+      showOverlay("none");
+      renderer.requestRender();
+    }
+  });
+  attachClickOutside(leaderDim, () => {
+    showOverlay("none");
+    renderer.requestRender();
+  });
   renderer.keyInput.on("keypress", (key) => {
     if (tokenPromptBox.visible) {
       if (key.name === "escape") {
@@ -6890,21 +7779,7 @@ ${pack.description ?? ""}`;
           return;
         }
         if (key.name === "enter" || key.name === "return") {
-          const sel = historySelect.getSelectedOption();
-          if (sel?.value) {
-            const entry = sel.value.entry;
-            showOverlay("none");
-            if (!entry) return;
-            if (entry.mode === "trending") {
-              if (entry.tab)
-                trendingTab = entry.tab;
-              loadTrending();
-            } else {
-              searchInput.value = entry.query;
-              showSearchMode();
-              doSearch(entry.query);
-            }
-          }
+          activateOverlaySelection();
           return;
         }
         return;
@@ -6923,9 +7798,7 @@ ${pack.description ?? ""}`;
           return;
         }
         if (key.name === "enter" || key.name === "return") {
-          const sel = bookmarksSelect.getSelectedOption();
-          if (sel?.value)
-            openUrl(sel.value.repo?.url ?? "");
+          activateOverlaySelection();
           return;
         }
         return;
@@ -6942,54 +7815,21 @@ ${pack.description ?? ""}`;
           return;
         }
         if (key.name === "enter" || key.name === "return") {
-          const sel = savedSelect.getSelectedOption();
-          if (sel?.value) {
-            const s = sel.value;
-            showOverlay("none");
-            touchSavedSearch(s.name);
-            if (s.mode === "trending") {
-              if (s.tab) trendingTab = s.tab;
-              loadTrending();
-            } else {
-              searchInput.value = s.query;
-              showSearchMode();
-              currentSort = s.sort;
-              currentLimit = s.limit;
-              setToolbar();
-              doSearch(s.query);
-            }
-          }
+          activateOverlaySelection();
           return;
         }
         return;
       }
       if (currentOverlay === "topics") {
         if (key.name === "enter" || key.name === "return") {
-          const sel = topicsSelect.getSelectedOption();
-          if (sel?.value) {
-            const topic = sel.value;
-            showOverlay("none");
-            searchInput.value = `topic:${topic.name ?? ""}`;
-            showSearchMode();
-            doSearch(`topic:${topic.name}`);
-          }
+          activateOverlaySelection();
           return;
         }
         return;
       }
       if (currentOverlay === "export") {
         if (key.name === "enter" || key.name === "return") {
-          const sel = exportSelect.getSelectedOption();
-          if (sel?.value && currentRepos.length > 0) {
-            const format2 = sel.value;
-            const path = exportToFile(currentRepos, format2);
-            showOverlay("none");
-            setStatus(`\u2713 Exported to ${path}`);
-          } else {
-            setStatus("No results to export");
-            showOverlay("none");
-          }
-          renderer.requestRender();
+          activateOverlaySelection();
           return;
         }
         return;
@@ -7018,26 +7858,13 @@ ${pack.description ?? ""}`;
       }
       if (currentOverlay === "share") {
         if (key.name === "enter" || key.name === "return") {
-          const sel = shareSelect.getSelectedOption();
-          if (sel?.value) {
-            const opt = resultsSelect.getSelectedOption();
-            const repo = opt?.value;
-            if (repo) {
-              const text = formatShare(repo, sel.value);
-              copyToClipboard(text).then((ok) => {
-                showOverlay("none");
-                setStatus(ok ? "\u2713 Copied!" : "Clipboard not available");
-              });
-            }
-          }
-          renderer.requestRender();
+          activateOverlaySelection();
           return;
         }
         return;
       }
       if (currentOverlay === "help") {
-        showOverlay("none");
-        renderer.requestRender();
+        activateOverlaySelection();
         return;
       }
       if (currentOverlay === "update") {
@@ -7062,29 +7889,7 @@ ${pack.description ?? ""}`;
           return;
         }
         if (key.name === "enter" || key.name === "return") {
-          const action = ["now", "later", "never"][updateSelectedOption];
-          if (action === "now") {
-            showOverlay("none");
-            recordPreUpdateState(cachedVersion ?? "");
-            performUpdate().then((ok) => {
-              if (ok) {
-                setStatus("\u2713 Update complete \u2014 restart ghfind");
-              } else {
-                setStatus("\u2717 Update failed \u2014 check terminal output");
-              }
-            }).catch(() => {
-              setStatus("\u2717 Update failed \u2014 check terminal output");
-            });
-          } else if (action === "never") {
-            suppressUpdateNotices();
-            showOverlay("none");
-            setStatus("Update notices suppressed");
-          } else {
-            snoozeUpdateNotices(3);
-            showOverlay("none");
-            setStatus("Update reminder snoozed for 3 days");
-          }
-          renderer.requestRender();
+          runUpdateOption(updateSelectedOption);
           return;
         }
         return;
@@ -7107,8 +7912,14 @@ ${pack.description ?? ""}`;
       toggleGraph();
       return;
     }
-    if (key.name === "space" && !searchInput.focused) {
-      showLeaderMenu();
+    if (key.name === "escape") {
+      if (currentOverlay !== "none") {
+        showOverlay("none");
+        setToolbar();
+      } else {
+        showLeaderMenu();
+      }
+      renderer.requestRender();
       return;
     }
     if (!searchInput.focused && errorHint) {
@@ -7663,7 +8474,7 @@ function formatPackageLines(pkgs) {
 function asMcpToolError(err) {
   return new McpToolError(err instanceof Error ? err.message : String(err));
 }
-var TRENDING_QUERY = { keywords: [], qualifiers: [], raw: "trending" };
+var TRENDING_QUERY = trendingQuery();
 var REPO_SORTS = ["best-match", "stars", "updated", "forks"];
 var SKILL_SOURCES = ["local", "registry"];
 var TRENDING_SINCE = ["daily", "weekly", "monthly"];
@@ -7710,6 +8521,17 @@ var TOOLS = [
       const token = resolveToken(state, args.token);
       const provider = createGitHubSearch(void 0, token ? [token] : []);
       const parsed = parseQuery(query);
+      try {
+        validateQuery(parsed);
+      } catch (err) {
+        if (err instanceof BadQueryError) {
+          return {
+            text: `Invalid query: ${err.detail}${err.hint ? ` Try: ${err.hint}` : ""}`,
+            data: { totalCount: 0, repos: [], invalidQuery: true }
+          };
+        }
+        throw err;
+      }
       const options = {
         limit,
         sort,
@@ -8667,6 +9489,7 @@ Options:
 }
 function buildSearchContext(flags) {
   const parsed = applyFlagFilters(parseQuery(flags.query), {});
+  validateQuery(parsed);
   return {
     query: flags.query,
     parsed,
@@ -9098,17 +9921,14 @@ async function runNonInteractive(flags, outputFormat) {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
       }
-      const response = await trendingSearch.search(
-        { keywords: [], qualifiers: [], raw: "trending" },
-        {
-          limit: 25,
-          sort: "stars",
-          json: false,
-          verbose: false,
-          trendingSince: since,
-          ...language ? { trendingLanguage: language } : {}
-        }
-      );
+      const response = await trendingSearch.search(trendingQuery(), {
+        limit: 25,
+        sort: "stars",
+        json: false,
+        verbose: false,
+        trendingSince: since,
+        ...language ? { trendingLanguage: language } : {}
+      });
       if (outputFormat) {
         console.log(format(response.repos, outputFormat));
       } else if (flags.count) {