github-search-cli 9.8.2 → 9.9.0

package/src/errors.ts

@@ -20,6 +20,39 @@ export class NetworkError extends SearchCliError {
   }
 }
 
+/**
+ * HTTP 401 — the configured GitHub token was rejected.
+ * Distinct from NetworkError: connectivity is fine, the credential is not.
+ */
+export class AuthError extends SearchCliError {
+  constructor() {
+    const msg =
+      "⚠ Bad GitHub token (401). Press [t] to fix it, [u] to search without one";
+    super("GitHub API returned 401 (invalid or revoked token)", msg);
+    this.name = "AuthError";
+  }
+}
+
+/**
+ * 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(public readonly detail: string = "GitHub API returned 403") {
+    const 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";
+  }
+}
+
 export class RateLimitError extends SearchCliError {
   constructor(
     public readonly hasToken: boolean,
@@ -34,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

@@ -47,6 +47,17 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "PageUp", action: "Scroll to top of results" },
       ],
     },
+    {
+      title: " Error Recovery ",
+      titleColor: "red",
+      rows: [
+        { keys: "r", action: "Retry after an error" },
+        { keys: "t", action: "Fix GitHub token (401/403)" },
+        { keys: "u", action: "Search without a token (401)" },
+        { keys: "c", action: "Change token (rate limit)" },
+      ],
+      note: "Active only while the matching error is in the status bar.",
+    },
     {
       title: " Trending Mode ",
       titleColor: "yellow",

package/src/image-loader.ts

@@ -6,6 +6,7 @@
  * inline `data:` URIs. Only some of them are worth downloading, and all of
  * the downloads are cached because a README is re-opened often.
  */
+import { declaresTooSmall, type DeclaredSize } from "./markdown-images";
 
 /** Reject anything bigger than this before buffering it. */
 export const MAX_IMAGE_BYTES = 6 * 1024 * 1024;
@@ -263,8 +264,7 @@ async function loadImageBytes(
   }
 }
 
-/**
- * Absolute URL of the README file itself, used as the base for relative
+/** Absolute URL of the README file itself, used as the base for relative
  * image paths.
  */
 export function readmeBaseUrl(
@@ -275,3 +275,58 @@ export function readmeBaseUrl(
 ): string {
   return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
 }
+
+/**
+ * Pixel size an image declares about itself, read from its header, or
+ * `undefined` when the runtime has no image codec or the bytes are unreadable.
+ * `Bun.Image.metadata()` reads only the header — no pixel decode — so this is
+ * cheap to run on bytes that are already in hand.
+ */
+async function imageSizeFromBytes(
+  bytes: Uint8Array,
+): Promise<DeclaredSize | undefined> {
+  const ImageCtor = (
+    globalThis as {
+      Bun?: {
+        Image?: new (
+          input: Uint8Array,
+          constructorOptions?: { maxPixels?: number },
+        ) => {
+          metadata(): Promise<{ width: number; height: number }>;
+        };
+      };
+    }
+  ).Bun?.Image;
+  if (!ImageCtor) return undefined;
+  try {
+    const meta = await new ImageCtor(bytes).metadata();
+    if (!meta.width || !meta.height) return undefined;
+    return { width: meta.width, height: meta.height };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether a downloaded image is worth rasterising.
+ *
+ * A reference that declares its size in the README is trusted (`declared`);
+ * one that doesn't is measured from the image header. Images below the
+ * 100 px floor are rejected *after* the download but *before* any pixel
+ * decode — markdown `![]()` images carry no declared size, so this is the
+ * only place their real size can be checked, and the header read is the
+ * cheapest check that works.
+ *
+ * On a runtime without `Bun.Image` (plain Node) there is nothing to measure
+ * with, so the image is accepted and left to the rasteriser, which fails
+ * into a caption anyway.
+ */
+export async function shouldRenderImage(
+  bytes: Uint8Array,
+  declared?: DeclaredSize,
+): Promise<boolean> {
+  if (declared) return !declaresTooSmall(declared);
+  const measured = await imageSizeFromBytes(bytes);
+  if (!measured) return true;
+  return !declaresTooSmall(measured);
+}

package/src/markdown-images.ts

@@ -14,6 +14,26 @@ export interface InlineTokenLike {
   tokens?: InlineTokenLike[];
 }
 
+/**
+ * A pixel size an image reference declares about itself — the `width`/`height`
+ * attributes of an `<img>` tag, or the dimensions `Bun.Image.metadata()` reads
+ * from an image header. `undefined` means "not declared".
+ */
+export interface DeclaredSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Images whose larger declared edge is below this are skipped before any
+ * request is made. Badges and 48x48 sponsor avatars are unreadable at cell
+ * resolution and, at 24 rows per image, a README full of them is unusable —
+ * 648 avatars in `openclaw/openclaw` measured 15,552 rows and 28 s to open.
+ * The README is the authority here: it can hide an image whose declared size
+ * understates it, which is judged better than a screen full of avatars.
+ */
+export const MIN_IMAGE_PIXELS = 100;
+
 /** Minimal shape of a marked block token. */
 export interface BlockTokenLike extends InlineTokenLike {
   depth?: number;
@@ -22,12 +42,55 @@ export interface BlockTokenLike extends InlineTokenLike {
 export interface ImageRef {
   href: string;
   alt: string;
+  /** Size the reference declares about itself, when it does. */
+  declared?: DeclaredSize;
+  /** Link target when the image is wrapped in a link (`[![alt](src)](url)`). */
+  linkUrl?: string;
 }
 
 const IMG_TAG = /<img\b[^>]*?src\s*=\s*["']([^"']+)["'][^>]*>/gi;
 const ALT_ATTR = /\balt\s*=\s*["']([^"']*)["']/i;
+const LENGTH_ATTR = /\b(width|height)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+/** Whole-value integers, with or without a `px` suffix. */
+const PIXEL_VALUE = /^(\d+)(?:px)?$/i;
 const HTML_TAG = /<\/?[a-z][^>]*>/gi;
 
+/**
+ * Pixel size an `<img>` tag declares via its `width`/`height` attributes, or
+ * `undefined` when it declares none. Only whole pixel values count —
+ * percentages (`width="100%"`) say nothing about real pixels, so they are
+ * ignored rather than read as a 100 px image.
+ */
+export function declaredImageSize(tag: string): DeclaredSize | undefined {
+  const values: Partial<Record<"width" | "height", number>> = {};
+  for (const [, name, dq, sq] of tag.matchAll(LENGTH_ATTR)) {
+    const raw = dq ?? sq ?? "";
+    const match = PIXEL_VALUE.exec(raw.trim());
+    if (!match) continue;
+    const n = Number.parseInt(match[1], 10);
+    if (Number.isFinite(n) && n > 0) {
+      values[name as "width" | "height"] = n;
+    }
+  }
+  if (values.width === undefined && values.height === undefined)
+    return undefined;
+  return {
+    width: values.width ?? values.height ?? 0,
+    height: values.height ?? values.width ?? 0,
+  };
+}
+
+/**
+ * Whether a reference declaring `size` is too small to render: an edge under
+ * the floor (the shipped contract — "images declaring an edge under 100px are
+ * skipped"). `undefined` (nothing declared) is never too small — callers
+ * decide from real pixels or render and let the rasteriser cap it.
+ */
+export function declaresTooSmall(size: DeclaredSize | undefined): boolean {
+  if (!size) return false;
+  return size.width < MIN_IMAGE_PIXELS || size.height < MIN_IMAGE_PIXELS;
+}
+
 /** Images embedded as raw `<img>` tags, when there's no other content. */
 function imagesFromHtml(raw: string | undefined): ImageRef[] {
   if (!raw || !/<img\b/i.test(raw)) return [];
@@ -43,7 +106,7 @@ function imagesFromHtml(raw: string | undefined): ImageRef[] {
   for (const match of raw.matchAll(IMG_TAG)) {
     const tag = match[0];
     const alt = ALT_ATTR.exec(tag)?.[1] ?? "";
-    refs.push({ href: match[1], alt });
+    refs.push({ href: match[1], alt, declared: declaredImageSize(tag) });
   }
   return refs;
 }
@@ -81,13 +144,29 @@ export function inlinePlainText(tokens: InlineTokenLike[] | undefined): string {
  */
 export function extractImageRefs(token: BlockTokenLike): ImageRef[] | null {
   const images: ImageRef[] = [];
+  let linkUrl: string | undefined;
 
   const collect = (inline: InlineTokenLike): boolean => {
     if (inline.type === "image") {
       if (inline.href)
-        images.push({ href: inline.href, alt: inline.text ?? "" });
+        images.push({ href: inline.href, alt: inline.text ?? "", linkUrl });
       return true;
     }
+    if (inline.type === "link" || inline.type === "linkReference") {
+      // `[![alt](img)](url)` — the badge-and-screenshot shape. marked hands
+      // the image to us as a child of the link token, so recurse; rejecting
+      // the block here discarded the image entirely (sst/opencode,
+      // withastro/astro). A link whose content is prose still fails the
+      // inner `text` check, so those blocks stay prose.
+      if (inline.tokens?.length) {
+        const outer = linkUrl;
+        linkUrl = inline.href || outer;
+        const ok = inline.tokens.every(collect);
+        linkUrl = outer;
+        return ok;
+      }
+      return false;
+    }
     if (inline.type === "html") {
       const refs = imagesFromHtml(inline.raw);
       if (refs.length > 0) {
@@ -111,7 +190,7 @@ export function extractImageRefs(token: BlockTokenLike): ImageRef[] | null {
 
   if (token.type === "html") {
     const refs = imagesFromHtml(token.raw);
-    return refs.length > 0 ? refs : null;
+    return refs.length > 0 ? dropTooSmall(refs) : null;
   }
 
   const inline = token.tokens ?? [];
@@ -119,5 +198,15 @@ export function extractImageRefs(token: BlockTokenLike): ImageRef[] | null {
   for (const child of inline) {
     if (!collect(child)) return null;
   }
-  return images.length > 0 ? images : null;
+  return images.length > 0 ? dropTooSmall(images) : null;
+}
+
+/**
+ * Filter out refs the README declares too small to be worth a request.
+ * An empty return means "pure image block, but nothing in it is worth
+ * drawing" — distinct from `null` (prose), so the view can render neither
+ * prose nor the raw markdown of a filtered-out image.
+ */
+function dropTooSmall(refs: ImageRef[]): ImageRef[] {
+  return refs.filter((image) => !declaresTooSmall(image.declared));
 }

package/src/markdown-view.ts

@@ -24,11 +24,12 @@ import {
   type HalfBlockImage,
   type Rgb,
 } from "./image-render";
-import { resolveReadmeImageUrl } from "./image-loader";
+import { resolveReadmeImageUrl, shouldRenderImage } from "./image-loader";
 import {
   extractImageRefs,
   inlinePlainText,
   type BlockTokenLike,
+  type DeclaredSize,
   type ImageRef,
 } from "./markdown-images";
 
@@ -105,17 +106,21 @@ function rgba(color: Rgb): RGBA {
 }
 
 /** Half-block rows as one styled-text block (one line per image row). */
-function imageStyledText(image: HalfBlockImage): StyledText {
+function imageStyledText(image: HalfBlockImage, linkUrl?: string): StyledText {
   const chunks: TextChunk[] = [];
   toImageRuns(image).forEach((runs, rowIndex) => {
     if (rowIndex > 0) chunks.push({ __isChunk: true, text: "\n" });
     for (const run of runs) {
-      chunks.push({
+      const chunk: TextChunk = {
         __isChunk: true,
         text: run.text,
         fg: rgba(run.top),
         bg: rgba(run.bottom),
-      });
+      };
+      // `[![alt](img)](url)` keeps its link: OSC 8 on the image cells, so a
+      // click in the terminal opens the same URL the prose version would.
+      if (linkUrl) chunk.link = { url: linkUrl };
+      chunks.push(chunk);
     }
   });
   return new StyledText(chunks);
@@ -158,17 +163,26 @@ export function createMarkdownView(opts: MarkdownViewOptions): MarkdownView {
     width: "100%",
   });
 
-  const caption = (label: string, color = muted()) =>
+  const caption = (label: string, linkUrl?: string, color = muted()) =>
     new TextRenderable(renderer, {
-      content: `  ${label}`,
-      fg: color,
+      content: new StyledText([
+        {
+          __isChunk: true,
+          text: `  ${label}`,
+          fg: RGBA.fromHex(color),
+          ...(linkUrl ? { link: { url: linkUrl } } : {}),
+        },
+      ]),
       bg: bg(),
       wrapMode: "word",
       flexShrink: 0,
       width: "100%",
     });
 
-  const rasterize = (url: string): Promise<HalfBlockImage | null> => {
+  const rasterize = (
+    url: string,
+    declared?: DeclaredSize,
+  ): Promise<HalfBlockImage | null> => {
     // Size is part of the key: a resized terminal needs fresh cells.
     const maxCols = Math.max(8, Math.floor(opts.getImageWidth?.() ?? 100));
     const key = `${maxCols}|${url}`;
@@ -179,6 +193,11 @@ export function createMarkdownView(opts: MarkdownViewOptions): MarkdownView {
       if (!loader) return null;
       const bytes = await loader(url);
       if (!bytes) return null;
+      // Size gate before any pixel decode. Declared sizes were already
+      // filtered at parse time (markdown-images.ts); markdown `![]()`
+      // images carry no declared size, so they are measured from the image
+      // header here — the rejected `null` is cached like any other failure.
+      if (!(await shouldRenderImage(bytes, declared))) return null;
       return rasterizeImage(bytes, {
         maxCols,
         maxRows: maxImageRows,
@@ -199,28 +218,29 @@ export function createMarkdownView(opts: MarkdownViewOptions): MarkdownView {
   const imageNode = (image: ImageRef): Renderable => {
     const label = `🖼  ${image.alt.trim() || "image"}`;
     const url = imageBase ? resolveReadmeImageUrl(image.href, imageBase) : null;
-    if (!imagesEnabled || !url || !opts.loadImage) return caption(label);
+    if (!imagesEnabled || !url || !opts.loadImage)
+      return caption(label, image.linkUrl);
 
     const container = new BoxRenderable(renderer, {
       flexDirection: "column",
       flexShrink: 0,
       width: "100%",
     });
-    const placeholder = caption(`${label}  (loading…)`);
+    const placeholder = caption(`${label}  (loading…)`, image.linkUrl);
     container.add(placeholder);
 
-    void rasterize(url).then(
+    void rasterize(url, image.declared).then(
       (cells) => {
         // The document may have been replaced (or the overlay closed) while
         // the image was downloading.
         if (container.isDestroyed || !container.parent) return;
         container.remove(placeholder);
         placeholder.destroy();
-        container.add(caption(label));
+        container.add(caption(label, image.linkUrl));
         if (cells) {
           container.add(
             new TextRenderable(renderer, {
-              content: imageStyledText(cells),
+              content: imageStyledText(cells, image.linkUrl),
               bg: bg(),
               wrapMode: "none",
               selectable: false,
@@ -270,17 +290,26 @@ export function createMarkdownView(opts: MarkdownViewOptions): MarkdownView {
     ): Renderable | undefined => {
       if (token.type === "heading") return headingNode(token);
       const images = extractImageRefs(token);
-      if (images && images.length > 0) {
-        const box = new BoxRenderable(renderer, {
-          flexDirection: "column",
+      if (images === null) return undefined; // prose: default rendering
+      if (images.length === 0) {
+        // Pure image block whose refs the README declares too small to be
+        // worth drawing (openclaw's 648 48x48 avatars). Render an empty
+        // block rather than falling through to prose, which would print the
+        // raw markdown of the filtered-out image.
+        return new BoxRenderable(renderer, {
           flexShrink: 0,
           width: "100%",
-          marginTop: 1,
+          height: 0,
         });
-        for (const image of images) box.add(imageNode(image));
-        return box;
       }
-      return undefined;
+      const box = new BoxRenderable(renderer, {
+        flexDirection: "column",
+        flexShrink: 0,
+        width: "100%",
+        marginTop: 1,
+      });
+      for (const image of images) box.add(imageNode(image));
+      return box;
     };
 
   renderable.renderNode = buildRenderNode();

package/src/mcp-server.ts

@@ -29,6 +29,8 @@ import {
   createGitHubSearch,
   createTrendingSearch,
   resolveTrendingLanguage,
+  trendingQuery,
+  validateQuery,
 } from "./search";
 import {
   createPackageSearch,
@@ -55,6 +57,7 @@ import {
   type SkillSource,
 } from "./skill-finder";
 import { getVersion } from "./version";
+import { RateLimitError, BadQueryError } from "./errors";
 
 // ─── Protocol constants ────────────────────────────────────────────────
 
@@ -214,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 ─────────────────────────────────────────────────────
 
@@ -270,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,
@@ -277,7 +294,22 @@ const TOOLS: ToolDefinition[] = [
         verbose: false,
         token,
       };
-      const response = await provider.search(parsed, options);
+      // The adapter no longer swallows rate limits as empty results — it
+      // throws RateLimitError. Convert it to the structured flag here so
+      // agents still get backoff advice (a tool failure reads as breakage;
+      // the flag reads as retry-later).
+      let response: Awaited<ReturnType<typeof provider.search>>;
+      try {
+        response = await provider.search(parsed, options);
+      } catch (err) {
+        if (err instanceof RateLimitError) {
+          return {
+            text: `GitHub API rate limit exceeded for "${query}". Set a token (GITHUB_TOKEN or the tool's token argument) to raise the limit from 60/hr to 5,000/hr.`,
+            data: { totalCount: 0, repos: [], rateLimited: true },
+          };
+        }
+        throw err;
+      }
       const repos = rankRepos(response.repos, sort);
 
       // Make agent searches visible in the user's TUI history (best-effort).

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({