github-search-cli 9.7.1 → 9.8.1

package/src/readme.ts

@@ -0,0 +1,54 @@
+/**
+ * README retrieval.
+ *
+ * A repository's README can live at one of three URLs, and the first guess
+ * ("main") 404s often enough that awaiting the candidates one at a time
+ * triples the time before any text appears. All three are therefore fired at
+ * once and the first *usable* response wins.
+ */
+import { readmeBaseUrl } from "./image-loader";
+
+export interface Readme {
+  /** The raw README markdown (or reStructuredText). */
+  text: string;
+  /**
+   * Where the README came from. Its own URL doubles as the base for resolving
+   * relative image paths, so it must match the branch that actually served.
+   */
+  sourceUrl: string;
+}
+
+/**
+ * Candidate README locations, most likely first.
+ */
+const CANDIDATES: ReadonlyArray<readonly [string, string]> = [
+  ["main", "README.md"],
+  ["master", "README.md"],
+  ["main", "README.rst"],
+];
+
+export async function fetchReadme(
+  owner: string,
+  repo: string,
+  opts: { token?: string; fetchImpl?: typeof fetch } = {},
+): Promise<Readme | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const headers: Record<string, string> = { "User-Agent": "ghfind/1.0" };
+  if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+
+  const attempts = CANDIDATES.map(async ([branch, file]) => {
+    const url = readmeBaseUrl(owner, repo, branch, file);
+    const res = await fetchImpl(url, { headers });
+    // Reject rather than resolve with null: Promise.any settles on the first
+    // *fulfilled* promise, so a 404 that resolved would beat the real README.
+    if (!res.ok) throw new Error(`no readme at ${url}`);
+    return { text: await res.text(), sourceUrl: url } satisfies Readme;
+  });
+
+  try {
+    return await Promise.any(attempts);
+  } catch {
+    // AggregateError: every candidate failed.
+    return null;
+  }
+}

package/src/skill-finder.ts

@@ -0,0 +1,445 @@
+/**
+ * skill-finder.ts — keyword search over agent skills, from two sources.
+ *
+ * Agents start a session not knowing which skills this machine has, and the
+ * public skills ecosystem is searched through a web page. This module gives
+ * both a single seam:
+ *
+ *   source      where results come from                          transport
+ *   ─────────── ──────────────────────────────────────────────── ─────────────
+ *   local       SKILL.md files installed under the four roots    filesystem
+ *   registry    skills.sh public ecosystem                      HTTPS (public)
+ *
+ * Everything here is read-only: nothing is downloaded, installed, or written.
+ * Registry results carry the `npx skills add` command for a human or agent to
+ * run deliberately.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import type { Dirent } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** Where an installed skill was found, and what it says about itself. */
+export interface LocalSkillHit {
+  /** The skill's frontmatter `name`. Also the `ghfind skill <name>` selector. */
+  name: string;
+  /** One-line summary from frontmatter (newlines collapsed). */
+  description: string;
+  /** Absolute path to the SKILL.md that won de-duplication. */
+  path: string;
+  /** Human-readable root the skill came from (home abbreviated to `~`). */
+  origin: string;
+}
+
+/** One skill from the public skills.sh ecosystem. */
+export interface RegistrySkillHit {
+  /** `owner/repo/skillId` — the unique ecosystem id. */
+  id: string;
+  /** Source repository, `owner/repo`. */
+  source: string;
+  /** Skill id within that repository. */
+  skillId: string;
+  /** Display name (the ecosystem sometimes supplies a title-case name). */
+  name: string;
+  /** Install count, the ecosystem's popularity signal. */
+  installs: number;
+  /** Command a human or agent can run to install it. */
+  installCommand: string;
+  /** Page for the skill on skills.sh. */
+  url: string;
+}
+
+export interface LocalSkillSearchResult {
+  query: string;
+  source: "local";
+  count: number;
+  skills: LocalSkillHit[];
+}
+
+export interface RegistrySkillSearchResult {
+  query: string;
+  source: "registry";
+  count: number;
+  skills: RegistrySkillHit[];
+}
+
+/** A skill search outcome, discriminated by `source`. */
+export type SkillSearchResult =
+  LocalSkillSearchResult | RegistrySkillSearchResult;
+
+export type SkillSource = "local" | "registry";
+
+/** The skills.sh search endpoint (public, no auth). */
+export const REGISTRY_SEARCH_ENDPOINT = "https://skills.sh/api/search";
+
+/** Shortest accepted query. skills.sh rejects anything shorter with HTTP 400. */
+export const MIN_QUERY_LENGTH = 2;
+
+/** Result cap, applied to both sources. */
+export const MAX_SKILL_RESULTS = 100;
+
+// ─── Local roots ──────────────────────────────────────────────────────────
+
+/** One scan root: where it is, and the label results carry. */
+interface SkillRoot {
+  path: string;
+  label: string;
+}
+
+/** Abbreviate a path for display: home becomes `~`, separators become `/`. */
+function displayPath(path: string): string {
+  const home = homedir();
+  const normalized = path.replace(/\\/g, "/");
+  const homeNorm = home.replace(/\\/g, "/").replace(/\/$/, "");
+  if (normalized === homeNorm) return "~";
+  if (normalized.startsWith(`${homeNorm}/`)) {
+    return `~${normalized.slice(homeNorm.length)}`;
+  }
+  return normalized;
+}
+
+/**
+ * The four roots scanned for installed skills, highest priority first.
+ *
+ * User-level roots outrank project-level ones, and `~/.codex/skills` outranks
+ * `~/.agents/skills`: the two overlap heavily on real machines, and the
+ * Codex-managed copy is the one its own tooling reads.
+ */
+export function defaultSkillRoots(cwd: string = process.cwd()): string[] {
+  const home = homedir();
+  return [
+    join(home, ".codex", "skills"),
+    join(home, ".agents", "skills"),
+    join(cwd, ".codex", "skills"),
+    join(cwd, ".github", "skills"),
+  ];
+}
+
+/**
+ * Scan roots in priority order. `GHFIND_SKILL_ROOTS` overrides the defaults —
+ * the seam tests and the MCP tool use it to point at a fixture directory
+ * instead of the real machine. It is split on the platform delimiter only
+ * (`;` on Windows, `:` elsewhere), so a Windows drive letter survives.
+ */
+export function resolveSkillRoots(cwd: string = process.cwd()): SkillRoot[] {
+  const override = process.env.GHFIND_SKILL_ROOTS;
+  const paths = override?.trim()
+    ? override
+        .split(delimiter)
+        .filter((p) => p.trim())
+        .map((p) => p.trim())
+    : defaultSkillRoots(cwd);
+  return paths.map((path) => ({ path, label: displayPath(path) }));
+}
+
+// ─── Frontmatter ──────────────────────────────────────────────────────────
+
+/** Directories never worth walking into. Hidden dirs ARE walked (`.system`). */
+const SKIP_DIRS = new Set(["node_modules", ".git"]);
+
+/** Cap on directory depth, so a symlink loop cannot hang a scan. */
+const MAX_DEPTH = 4;
+
+/** Strip one layer of matching quotes from a frontmatter scalar. */
+function unquote(value: string): string {
+  const trimmed = value.trim();
+  if (
+    trimmed.length >= 2 &&
+    ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'")))
+  ) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+/**
+ * Read `name` and `description` out of a SKILL.md frontmatter block.
+ *
+ * Handles the three shapes real skills use: plain scalars, quoted scalars
+ * (`name: "imagegen"`), and folded/literal blocks (`description: >` followed
+ * by indented lines). Returns null when there is no frontmatter block.
+ */
+export function parseSkillFrontmatter(
+  text: string,
+): { name: string; description: string } | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!match) return null;
+  const lines = match[1].split(/\r?\n/);
+  const fields: Record<string, string> = {};
+  for (let i = 0; i < lines.length; i++) {
+    const field = /^([A-Za-z_][\w-]*):[ \t]*(.*)$/.exec(lines[i]);
+    if (!field) continue;
+    const key = field[1].toLowerCase();
+    const inline = field[2].trim();
+    if (inline === ">" || inline === "|" || /^[>|][-+]?$/.test(inline)) {
+      // Block scalar: gather the following more-indented lines.
+      const literal = inline.startsWith("|");
+      const parts: string[] = [];
+      while (i + 1 < lines.length && /^[ \t]+\S/.test(lines[i + 1])) {
+        parts.push(lines[++i].trim());
+      }
+      fields[key] = literal ? parts.join("\n") : parts.join(" ");
+    } else {
+      fields[key] = unquote(inline);
+    }
+  }
+  const name = fields.name ?? "";
+  if (!name) return null;
+  return { name, description: fields.description ?? "" };
+}
+
+// ─── Local scan ───────────────────────────────────────────────────────────
+
+/**
+ * Walk the roots and collect every readable SKILL.md, de-duplicated by name.
+ *
+ * The first root to claim a name wins; within a root the shallowest path wins
+ * (breadth-first order). Unreadable directories and malformed files are skipped
+ * rather than failing the whole scan — a scan is best-effort by nature.
+ */
+export function scanLocalSkills(
+  roots: SkillRoot[] = resolveSkillRoots(),
+): LocalSkillHit[] {
+  const byName = new Map<string, LocalSkillHit>();
+  for (const root of roots) {
+    for (const dir of walkDirs(root.path)) {
+      const entries = listDir(dir);
+      if (!entries) continue;
+      if (!entries.some((e) => e.isFile() && e.name === "SKILL.md")) continue;
+      const file = join(dir, "SKILL.md");
+      try {
+        const parsed = parseSkillFrontmatter(readFileSync(file, "utf-8"));
+        if (!parsed || byName.has(parsed.name)) continue;
+        byName.set(parsed.name, {
+          name: parsed.name,
+          description: parsed.description.replace(/\s+/g, " ").trim(),
+          path: file,
+          origin: root.label,
+        });
+      } catch {
+        // unreadable file — skip it, the rest of the scan still stands
+      }
+    }
+  }
+  return [...byName.values()];
+}
+
+/** Directory entries, or null when the directory is missing or unreadable. */
+function listDir(dir: string): Dirent[] | null {
+  try {
+    return readdirSync(dir, { withFileTypes: true }) as Dirent[];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Directories under `root`, breadth-first and depth-capped so a symlink loop
+ * cannot hang a scan. `node_modules` and `.git` are pruned; other hidden
+ * directories (e.g. `.system`) are walked.
+ */
+function* walkDirs(root: string): Generator<string> {
+  const queue: Array<[string, number]> = [[root, 0]];
+  while (queue.length > 0) {
+    const [dir, depth] = queue.shift() as [string, number];
+    const entries = listDir(dir);
+    if (!entries) continue;
+    yield dir;
+    if (depth >= MAX_DEPTH) continue;
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+      queue.push([join(dir, entry.name), depth + 1]);
+    }
+  }
+}
+
+// ─── Ranking ──────────────────────────────────────────────────────────────
+
+/** Match tiers, best first: exact name, name prefix, name, description. */
+function localMatchTier(hit: LocalSkillHit, needle: string): number | null {
+  const name = hit.name.toLowerCase();
+  if (name === needle) return 0;
+  if (name.startsWith(needle)) return 1;
+  if (name.includes(needle)) return 2;
+  if (hit.description.toLowerCase().includes(needle)) return 3;
+  return null;
+}
+
+/** Filter + rank local skills for a query. */
+export function rankLocalSkills(
+  hits: LocalSkillHit[],
+  query: string,
+  limit: number = MAX_SKILL_RESULTS,
+): LocalSkillHit[] {
+  const needle = query.trim().toLowerCase();
+  return hits
+    .map((hit) => ({ hit, tier: localMatchTier(hit, needle) }))
+    .filter(
+      (entry): entry is { hit: LocalSkillHit; tier: number } =>
+        entry.tier !== null,
+    )
+    .sort((a, b) => a.tier - b.tier || a.hit.name.localeCompare(b.hit.name))
+    .slice(0, clampLimit(limit))
+    .map((entry) => entry.hit);
+}
+
+/** Clamp a result limit into 1..MAX_SKILL_RESULTS. */
+export function clampLimit(limit: number): number {
+  const n = Math.trunc(Number(limit));
+  if (!Number.isFinite(n)) return MAX_SKILL_RESULTS;
+  return Math.min(Math.max(n, 1), MAX_SKILL_RESULTS);
+}
+
+/** Throw for queries both sources reject, before any work is done. */
+export function assertSearchableQuery(query: string): string {
+  const trimmed = query.trim();
+  if (trimmed.length < MIN_QUERY_LENGTH) {
+    throw new Error(
+      `Query must be at least ${MIN_QUERY_LENGTH} characters (got "${trimmed}").`,
+    );
+  }
+  return trimmed;
+}
+
+// ─── Search entry points ──────────────────────────────────────────────────
+
+/** Search skills installed on this machine. */
+export function searchLocalSkills(
+  query: string,
+  opts: { limit?: number; roots?: SkillRoot[] } = {},
+): LocalSkillSearchResult {
+  const trimmed = assertSearchableQuery(query);
+  const skills = rankLocalSkills(
+    scanLocalSkills(opts.roots ?? resolveSkillRoots()),
+    trimmed,
+    opts.limit ?? MAX_SKILL_RESULTS,
+  );
+  return { query: trimmed, source: "local", count: skills.length, skills };
+}
+
+/** Normalize one skills.sh search result. */
+function normalizeRegistrySkill(raw: unknown): RegistrySkillHit | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw as Record<string, unknown>;
+  const source = typeof obj.source === "string" ? obj.source : "";
+  const skillId = typeof obj.skillId === "string" ? obj.skillId : "";
+  if (!source || !skillId) return null;
+  const name =
+    typeof obj.name === "string" && obj.name.trim() ? obj.name : skillId;
+  const installs = typeof obj.installs === "number" ? obj.installs : 0;
+  const id =
+    typeof obj.id === "string" && obj.id ? obj.id : `${source}/${skillId}`;
+  return {
+    id,
+    source,
+    skillId,
+    name,
+    installs,
+    installCommand: `npx skills add ${source}@${skillId}`,
+    url: `https://skills.sh/${source}/${skillId}`,
+  };
+}
+
+/**
+ * Search the public skills.sh ecosystem.
+ *
+ * Read-only: results carry the command to install, never an install. Network
+ * and protocol failures surface as plain Errors with a user-facing message.
+ */
+export async function searchRegistrySkills(
+  query: string,
+  opts: { limit?: number; fetchImpl?: typeof fetch } = {},
+): Promise<RegistrySkillSearchResult> {
+  const trimmed = assertSearchableQuery(query);
+  const limit = clampLimit(opts.limit ?? MAX_SKILL_RESULTS);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${REGISTRY_SEARCH_ENDPOINT}?q=${encodeURIComponent(trimmed)}&limit=${limit}`;
+
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      headers: { Accept: "application/json", "User-Agent": "ghfind/1.0" },
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach skills.sh: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!res.ok) {
+    throw new Error(
+      `skills.sh returned HTTP ${res.status} for "${trimmed}". Retry, or search locally with --local.`,
+    );
+  }
+
+  let payload: unknown;
+  try {
+    payload = await res.json();
+  } catch {
+    throw new Error("skills.sh returned a response that was not JSON.");
+  }
+  const items = (payload as { skills?: unknown[] })?.skills ?? [];
+  const skills = items
+    .map(normalizeRegistrySkill)
+    .filter((s): s is RegistrySkillHit => s !== null)
+    .slice(0, limit);
+  return { query: trimmed, source: "registry", count: skills.length, skills };
+}
+
+/** Search skills by source — the single entry point CLI and MCP share. */
+export async function searchSkills(
+  query: string,
+  opts: {
+    source?: SkillSource;
+    limit?: number;
+    roots?: SkillRoot[];
+    fetchImpl?: typeof fetch;
+  } = {},
+): Promise<SkillSearchResult> {
+  if ((opts.source ?? "local") === "registry") {
+    return searchRegistrySkills(query, opts);
+  }
+  return searchLocalSkills(query, opts);
+}
+
+// ─── Formatting ───────────────────────────────────────────────────────────
+
+/** JSON payload for either source (the shape agents should parse). */
+export function formatSkillSearchJson(result: SkillSearchResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+/** Trim a description to one readable line for text output. */
+function shortDescription(description: string, width = 100): string {
+  if (description.length <= width) return description;
+  return `${description.slice(0, width - 1).trimEnd()}…`;
+}
+
+/** Human/agent-readable text for a search result. */
+export function formatSkillSearchText(result: SkillSearchResult): string {
+  if (result.count === 0) {
+    return result.source === "local"
+      ? `No installed skills match "${result.query}". Try --remote to search the skills.sh ecosystem.`
+      : `No skills.sh entries match "${result.query}".`;
+  }
+  if (result.source === "local") {
+    return result.skills
+      .map(
+        (s) => `${s.name}  (${s.origin})\n  ${shortDescription(s.description)}`,
+      )
+      .join("\n");
+  }
+  return result.skills
+    .map(
+      (s) =>
+        `${s.name}  ${s.installs.toLocaleString()} installs  [${s.source}]\n  ${s.installCommand}`,
+    )
+    .join("\n");
+}
+
+/** Names only — the pipe-friendly form (`ghfind skill search x --names`). */
+export function formatSkillSearchNames(result: SkillSearchResult): string {
+  return result.skills.map((s) => s.name).join("\n");
+}

package/src/tui.ts

@@ -74,7 +74,9 @@ import {
 import { saveSession, restoreSession } from "./session";
 import { fetchDeepDive, buildDeepDiveText } from "./deepdive";
 import { buildComparisonTable } from "./compare";
-import { renderMarkdown } from "./markdown-render";
+import { createMarkdownView } from "./markdown-view";
+import { fetchImageBytes } from "./image-loader";
+import { fetchReadme } from "./readme";
 import { fetchTopics } from "./explore";
 import { exportToFile, type ExportFormat } from "./output";
 import {
@@ -1079,12 +1081,22 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     paddingLeft: 2,
     paddingRight: 2,
   });
-  const updateText = new TextRenderable(renderer, {
+  // Version header only — the release notes below it are rendered markdown.
+  const updateHeader = new TextRenderable(renderer, {
     content: "",
     fg: colors.accent,
     bg: colors.surfaceDim,
   });
-  // ponytail: notes render as plain text with \n; keep it a column so lines stack
+  const updateNotes = createMarkdownView({
+    renderer,
+    colors,
+    // Notes ship with the release and are mostly prose/lists; skip the
+    // image pipeline in this narrow panel.
+    images: false,
+    background: colors.surfaceDim,
+  });
+  // ponytail: the notes are markdown now; keep the content a column so
+  // blocks stack and the scroll box can measure them.
   const updateScroll = new ScrollBoxRenderable(renderer, {
     flexGrow: 1,
     backgroundColor: colors.surfaceDim,
@@ -1187,7 +1199,8 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     paddingX: 1,
   });
   updateBox.add(updateScroll);
-  updateScroll.add(updateText);
+  updateScroll.add(updateHeader);
+  updateScroll.add(updateNotes.renderable);
   updateBox.add(updateOptionsRow);
   updateBox.add(updateFooter);
   root.add(updateDim);
@@ -1597,17 +1610,11 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     if (state.lastInstalledVersion === currentVersion) return;
     // We just upgraded — show notes for the new version
     const notes = fetchReleaseNotes(currentVersion);
-    // Box is 55% of the terminal; subtract border + padding so wrapped
-    // lines never clip horizontally.
-    const notesWidth = Math.max(
-      30,
-      Math.floor((process.stdout.columns || 80) * 0.55) - 8,
-    );
-    const notesBlock = notes
-      ? renderMarkdown(notes, { width: notesWidth })
-      : "  No release notes found for this version.";
     updateSelectedOption = 0;
-    updateText.content = `  Updated ghfind ${state.lastInstalledVersion} → ${currentVersion}\n\n${notesBlock}`;
+    updateHeader.content = `  Updated ghfind ${state.lastInstalledVersion} → ${currentVersion}\n`;
+    updateNotes.setContent(
+      notes ?? "_No release notes found for this version._",
+    );
     renderUpdateOptions();
     showOverlay("update");
   }
@@ -1625,14 +1632,8 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     if (latest) {
       updateSelectedOption = 0;
       const notes = fetchReleaseNotes(latest);
-      const notesWidth = Math.max(
-        30,
-        Math.floor((process.stdout.columns || 80) * 0.55) - 8,
-      );
-      const notesBlock = notes
-        ? renderMarkdown(notes, { width: notesWidth })
-        : `  A new version is available\n\n  Current: ${currentVersion}\n  Latest:   ${latest}\n\n  Run "npm install -g ghfind"`;
-      updateText.content = `  A new version is available\n\n  Current: ${currentVersion}\n  Latest:   ${latest}\n\n${notesBlock}`;
+      updateHeader.content = `  A new version is available\n\n  Current: ${currentVersion}\n  Latest:   ${latest}\n`;
+      updateNotes.setContent(notes ?? "Run `npm install -g ghfind` to update.");
       renderUpdateOptions();
       showOverlay("update");
     } else {
@@ -1852,15 +1853,22 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
       },
     },
   });
-  const readmeText = new TextRenderable(renderer, {
-    content: "",
-    fg: colors.text,
-    bg: colors.bg,
+  // Full markdown rendering (headings, tables, code, inline images).
+  const readmeView = createMarkdownView({
+    renderer,
+    colors,
+    loadImage: (url) => fetchImageBytes(url, { token: githubToken }),
+    getImageWidth: () => Math.max(24, (process.stdout.columns || 80) - 12),
   });
-  readmeScroll.add(readmeText);
+  readmeScroll.add(readmeView.renderable);
   readmeBox.add(readmeScroll);
+
+  const readmeFooterText = () =>
+    `  ↑↓/jk scroll  PgUp/PgDn page  i images: ${
+      readmeView.imagesEnabled ? "on" : "off"
+    }  Esc/q close`;
   const readmeFooter = new TextRenderable(renderer, {
-    content: "  ↑↓/jk scroll  Esc/q close",
+    content: readmeFooterText(),
     fg: colors.muted,
     bg: colors.bg,
     height: 1,
@@ -1876,33 +1884,21 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
       setStatus("No repo selected");
       return;
     }
-    readmeText.content = `  Loading README for ${repo.fullName}...`;
+    readmeView.setContent(`Loading README for ${repo.fullName}…`);
+    readmeFooter.content = readmeFooterText();
+    readmeScroll.scrollTop = 0;
     showOverlay("readme");
     try {
-      const headers: Record<string, string> = { "User-Agent": "ghfind/1.0" };
-      if (githubToken) headers.Authorization = `Bearer ${githubToken}`;
-      let text = "";
-      for (const path of [
-        `${repo.owner}/${repo.name}/main/README.md`,
-        `${repo.owner}/${repo.name}/master/README.md`,
-        `${repo.owner}/${repo.name}/main/README.rst`,
-      ]) {
-        const r = await fetch(`https://raw.githubusercontent.com/${path}`, {
-          headers,
-        });
-        if (r.ok) {
-          text = await r.text();
-          break;
-        }
-      }
-      if (!text) {
-        readmeText.content = `  (no README found for ${repo.fullName})`;
+      const readme = await fetchReadme(repo.owner, repo.name, {
+        token: githubToken,
+      });
+      if (readme) {
+        readmeView.setContent(readme.text, readme.sourceUrl);
       } else {
-        const termW = Math.max(40, (process.stdout.columns || 80) - 4);
-        readmeText.content = renderMarkdown(text, { width: termW });
+        readmeView.setContent(`_(no README found for ${repo.fullName})_`);
       }
     } catch {
-      readmeText.content = "  Failed to load README";
+      readmeView.setContent("_Failed to load README._");
     }
     renderer.requestRender();
   }
@@ -2505,6 +2501,24 @@ export async function launchBrowser(theme_override?: string): Promise<void> {
     }
   });
 
+  // Pasted content flows through "input"; purge JSON-shaped blobs that
+  // slipped into the query (a search line is never raw JSON: objects/arrays
+  // always arrive as paste payloads from API responses / deep-dive output).
+  searchInput.on("input", () => {
+    const v = searchInput.value;
+    if (v.length > 0) {
+      const t = v.trim();
+      if (
+        (t.startsWith("{") && t.endsWith("}")) ||
+        (t.startsWith("[") && t.endsWith("]"))
+      ) {
+        searchInput.value = "";
+        setStatus("Ignored JSON paste — search queries accept plain text");
+        renderer.requestRender();
+      }
+    }
+  });
+
   // Navigate results → update detail pane
   resultsSelect.on("selectionChanged", () => {
     const opt = resultsSelect.getSelectedOption();
@@ -2606,6 +2620,14 @@ ${pack.description ?? ""}`;
 
       // README viewer: scrollable, Esc/q already handled above
       if (currentOverlay === "readme") {
+        if (key.name === "i") {
+          readmeView.setImagesEnabled(!readmeView.imagesEnabled);
+          readmeFooter.content = readmeFooterText();
+          setStatus(
+            readmeView.imagesEnabled ? "README images on" : "README images off",
+          );
+          renderer.requestRender();
+        }
         return;
       }