github-search-cli 9.8.3 → 9.10.0

package/src/errors.ts

@@ -34,15 +34,21 @@ export class AuthError extends SearchCliError {
 }
 
 /**
- * HTTP 403 — authenticated but not allowed (SAML enforcement, resource
- * restrictions, secondary limits). Not the same as the rate-limit 403,
- * which is detected by an exhausted x-ratelimit-remaining header first.
+ * HTTP 403 that is NOT a primary rate limit (i.e. `x-ratelimit-remaining`
+ * was greater than zero). Three unrelated causes land here and the status
+ * code cannot tell them apart:
+ *   - the token's org enforces SAML SSO and has not authorized it
+ *   - a secondary/abuse rate limit (concurrent or rapid-fire requests)
+ *   - a valid token blocked by org or resource restrictions
+ * The old message asserted SSO unconditionally, which sent people to fix a
+ * credential problem that did not exist. Check GHFIND_LOG for the body.
  */
 export class ForbiddenError extends SearchCliError {
-  constructor() {
+  constructor(public readonly detail: string = "GitHub API returned 403") {
     const msg =
-      "⚠ Forbidden (403). If your org enforces SSO, authorize the token; [t] to change it";
-    super("GitHub API returned 403 (token lacks access)", msg);
+      `⚠ Forbidden (403) — ${detail}. Common causes: org SSO not authorizing the token, ` +
+      `or a secondary rate limit. Press [t] to change the token`;
+    super(msg, msg);
     this.name = "ForbiddenError";
   }
 }
@@ -61,17 +67,35 @@ export class RateLimitError extends SearchCliError {
 }
 
 export class BadQueryError extends SearchCliError {
-  constructor(public readonly detail: string) {
-    super(`Invalid query: ${detail}`, `⚠ Invalid query: ${detail}`);
+  /** A concrete, corrected query the user can retry with. */
+  constructor(
+    public readonly detail: string,
+    public readonly hint?: string,
+  ) {
+    super(
+      `Invalid query: ${detail}`,
+      hint
+        ? `⚠ Invalid query: ${detail}\n  Try: ${hint}`
+        : `⚠ Invalid query: ${detail}`,
+    );
     this.name = "BadQueryError";
   }
 }
 
 export class NoResultsError extends SearchCliError {
-  constructor(public readonly query: string) {
+  /** Concrete loosened queries to retry, most promising first. */
+  constructor(
+    public readonly query: string,
+    public readonly relaxations: string[] = [],
+  ) {
+    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}"`,
-      `🔍 No results for "${query}". Tips: check spelling, try fewer qualifiers, or [b]rowse trending`,
+      relaxations.length > 0
+        ? `No results for "${query}" — try loosening: ${relaxations.join(" / ")}`
+        : `No results for "${query}"`,
+      `🔍 No results for "${query}".\n  ${tips}`,
     );
     this.name = "NoResultsError";
   }

package/src/help.ts

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

package/src/mcp-server.ts

@@ -29,6 +29,8 @@ import {
   createGitHubSearch,
   createTrendingSearch,
   resolveTrendingLanguage,
+  trendingQuery,
+  validateQuery,
 } from "./search";
 import {
   createPackageSearch,
@@ -55,7 +57,7 @@ import {
   type SkillSource,
 } from "./skill-finder";
 import { getVersion } from "./version";
-import { RateLimitError } from "./errors";
+import { RateLimitError, BadQueryError } from "./errors";
 
 // ─── Protocol constants ────────────────────────────────────────────────
 
@@ -215,7 +217,7 @@ function asMcpToolError(err: unknown): McpToolError {
   return new McpToolError(err instanceof Error ? err.message : String(err));
 }
 
-const TRENDING_QUERY = { keywords: [], qualifiers: [], raw: "trending" };
+const TRENDING_QUERY = trendingQuery();
 
 // ─── Tool registry ─────────────────────────────────────────────────────
 
@@ -271,6 +273,20 @@ const TOOLS: ToolDefinition[] = [
 
       const provider = createGitHubSearch(undefined, token ? [token] : []);
       const parsed = parseQuery(query);
+      // Reject a malformed qualifier here rather than spending an API call:
+      // for an agent, GitHub's opaque 422 reads as breakage, whereas the
+      // specific message names the bad token and the fix.
+      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: SearchOptions = {
         limit,
         sort,

package/src/search-state.ts

@@ -14,6 +14,7 @@ import {
   createGitHubSearch,
   SearchModule,
   TrendingAdapter,
+  trendingQuery,
 } from "./search";
 import { restoreSession, saveSession } from "./session";
 import { appendHistory } from "./history";
@@ -155,16 +156,13 @@ export class SearchStateManager {
     this.state.trendingTab = tab;
     this.state.currentMode = "trending";
     try {
-      const response = await this.trendingSearch.search(
-        { keywords: [], qualifiers: [], raw: "trending" },
-        {
-          limit: 25,
-          sort: "stars",
-          json: false,
-          verbose: false,
-          trendingSince: tabSince(tab),
-        },
-      );
+      const response = await this.trendingSearch.search(trendingQuery(), {
+        limit: 25,
+        sort: "stars",
+        json: false,
+        verbose: false,
+        trendingSince: tabSince(tab),
+      });
       this.state.currentRepos = response.repos;
       this.state.totalCount = response.totalCount;
       appendHistory({