github-search-cli 9.8.2 → 9.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.8.2",
+  "version": "9.8.3",
   "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",

package/release-notes/9.8.3.md

@@ -0,0 +1,98 @@
+# v9.8.3
+
+Three things went wrong often enough to be worth a release: GitHub told you
+"Network error" for problems that had nothing to do with your network, you had
+to leave the TUI to fix a bad token, and a session file could hijack startup.
+The README image viewer also gained the last two cases from the 9.8.1 notice.
+
+## Errors now say what actually happened
+
+A rejected token and an authenticated-but-forbidden request were both reported
+as `Network error`, which named a connectivity problem you did not have. Now:
+
+- `401` — the token was rejected: **"Bad GitHub token (401)"**
+- `403` that is not the rate-limit case — e.g. SAML/SSO enforcement:
+  **"Forbidden (403)"**, naming the SSO case
+- `403` with `x-ratelimit-remaining: 0` — a rate limit, as before
+- `5xx` and genuine connectivity failures — still a network error
+
+A rate-limited search also used to _swallow_ the error and render as a silent,
+successful "no repositories found". The real message now reaches the status
+bar. For agents, the `ghfind_search_repos` MCP tool converts the error into the
+structured flag it already had — `rateLimited: true` plus backoff advice —
+because a tool failure reads as breakage while the flag reads as retry-later.
+
+## Recover from errors without leaving the TUI
+
+While the matching error is in the status bar:
+
+| Key | Action                                                          |
+| --- | --------------------------------------------------------------- |
+| `t` | Inline token prompt — saves to config, re-runs the failed query |
+| `u` | Clear the token and retry unauthenticated (401)                 |
+| `c` | Swap in a different token (rate limit)                          |
+| `r` | Retry the search or trending load                               |
+
+`Esc` cancels the prompt. The keys are scoped to that one error — any new
+search retires them, so `t` and `c` go back to cycling the theme and opening
+compare. Documented in the help overlay and the README.
+
+## A corrupted session no longer hijacks startup
+
+A `session.json` whose query field held an MCP handshake blob (a client piped
+its `initialize` request into the search box) made every launch skip the landing
+menu and auto-run that garbage as a search. Two layers now:
+
+- Startup always shows the landing menu. A saved session restores preferences
+  (sort, limit, trending tab) and pre-fills the query when you pick Repo
+  Search, but never runs a search on its own.
+- Save and restore both go through `sanitizeSession()`. JSON-shaped or
+  oversized queries are dropped; a non-restorable mode, bad sort, `NaN` limit
+  or empty tab fall back to defaults. Reading from disk runs the same check as
+  writing, so an existing corrupt file cannot do it again.
+
+## Images wrapped in links render now
+
+The common badge-and-screenshot shape — `[![alt](shot.png)](https://example.com)`
+— rendered nothing at all. The markdown token walk treated any block containing
+a link token as prose and discarded it, so `sst/opencode` lost the only image in
+its README and `withastro/astro` lost 23 of its 25. The walk now recurses into
+link tokens: the image renders, and its cells carry an OSC 8 hyperlink to the
+original target, so clicking the image opens the same URL the prose version
+would have.
+
+## A README full of small images no longer floods the screen
+
+`openclaw/openclaw` has 661 `<img>` tags in its README, 648 of them 48×48
+sponsor avatars. Each rendered at 48 columns × 24 rows — a full screen per
+avatar — so opening the README downloaded 649 images (1.6 MB) and produced
+15,552 rows of output, in 28 seconds.
+
+Images the README declares smaller than 100 px on any edge are now filtered
+while parsing, before a single request is made. Images that declare no size
+(marked `![]()` syntax) are measured from the image header after download —
+`Bun.Image.metadata()` reads only the header, no pixel decode — and rejected
+before rasterising. Measured on the same README:
+
+    image urls fetched:  649 -> 1
+    wall time:       28,318 ms -> ~550 ms
+
+The trade-off is deliberate: a README that understates an image's declared size
+hides that image (two of openclaw's avatars declare `width="48"` but are
+420×420). The README is treated as the authority on its own layout; the
+alternative — trusting the image over the README — is exactly what made these
+pages unusable.
+
+## Verification
+
+516 tests (up from 482), plus `format:check`, `typecheck` and `lint` all green.
+New tests pin the HTTP status → error mapping end to end, the session
+sanitizers and the TUI startup contract, the link-recursion extraction
+(including prose-links staying prose and nested links taking the innermost
+href), the declared-size reader (percentages like `width="100%"` are ignored,
+`px` suffixes accepted), the header-only pixel gate, and end-to-end view
+behaviour: a linked-image block builds an image node instead of prose,
+declared-small images make no request, and undeclared images still reach the
+loader.
+
+`README.md` Known-limitations section rewritten to match; test counts synced.

package/src/errors.ts

@@ -20,6 +20,33 @@ 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 — 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.
+ */
+export class ForbiddenError extends SearchCliError {
+  constructor() {
+    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);
+    this.name = "ForbiddenError";
+  }
+}
+
 export class RateLimitError extends SearchCliError {
   constructor(
     public readonly hasToken: boolean,

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

@@ -55,6 +55,7 @@ import {
   type SkillSource,
 } from "./skill-finder";
 import { getVersion } from "./version";
+import { RateLimitError } from "./errors";
 
 // ─── Protocol constants ────────────────────────────────────────────────
 
@@ -277,7 +278,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.ts

@@ -15,7 +15,13 @@ import type {
   SortStrategy,
   CacheEntry,
 } from "./types";
-import { NetworkError, RateLimitError, ParseError } from "./errors";
+import {
+  NetworkError,
+  RateLimitError,
+  ParseError,
+  AuthError,
+  ForbiddenError,
+} from "./errors";
 import { parseTrendingHtml, type RawTrendingRepo } from "./trending-parser";
 
 export interface Logger {
@@ -448,7 +454,14 @@ export class GitHubSearchAdapter implements SearchAdapter {
             this.logger.error(
               `[github] non-rate-limit 403: ${body.slice(0, 200)}`,
             );
-            throw new NetworkError();
+            throw new ForbiddenError();
+          }
+          if (res.status === 401) {
+            const body = await res.text().catch(() => "");
+            this.logger.error(
+              `[github] auth rejected (401): ${body.slice(0, 200)}`,
+            );
+            throw new AuthError();
           }
           if (!res.ok) {
             const body = await res.text().catch(() => "");
@@ -492,6 +505,10 @@ export class GitHubSearchAdapter implements SearchAdapter {
           lastErr = undefined;
           break;
         } catch (err) {
+          // RateLimitError must propagate: swallowing it turns the failure
+          // into a silent zero-result "success" and the user never learns
+          // why their search died.
+          if (err instanceof RateLimitError) throw err;
           lastErr = err as Error;
           if (rateLimited) break;
         }