github-search-cli 9.1.1 → 9.3.0

package/README.md

@@ -22,14 +22,15 @@
 npm install -g github-search-cli
 ```
 
-> **No separate runtime needed!** The package bundles a Bun binary, so the TUI
-> works out of the box on Windows, macOS, and Linux — no Node FFI, no `--experimental-ffi`.
+> **No separate runtime needed!** Only requires Node.js 20+. The TUI needs Bun,
+> which is downloaded automatically at install time. Non-interactive modes work
+> with just Node.js.
 >
-> | Runtime     | TUI | CLI modes |
-> | ----------- | --- | --------- |
-> | Bundled Bun | ✅  | ✅        |
-> | System Bun  | ✅  | ✅        |
-> | Node 20+    | ✅  | ✅        |
+> | Platform              | TUI              | CLI modes |
+> | --------------------- | ---------------- | --------- |
+> | Node 20+              | ⚠ Bun required  | ✅        |
+> | Bun                   | ✅               | ✅        |
+> | Downloaded Bun        | ✅ auto-installed| ✅        |
 
 ## Use
 
@@ -191,17 +192,31 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 102 tests
+bun test         # 131 tests
 bun run build    # build dist/
 
 # Or with npm
 npm install
-npm start        # TUI (requires Node 20-22 for native FFI)
-npm test         # vitest (TUI render test needs Bun)
+npm start        # TUI (requires Node 20+)
+npm test         # 131 tests
 npm run build    # build dist/
 ```
 
 ---
+### v0.9.3
+- Fixed `c` keybinding in TUI not adding repos to comparison — missing closing brace in space-key handler broke all subsequent key handlers (`c`, `t`, `?`)
+- Widened compare table columns (min 35 chars) and added Description + URL rows for richer side-by-side comparison
+- Compare table now shows up to 5 topics per repo (was 3)
+- README viewer now renders full markdown (headings, code blocks, lists, tables, blockquotes, rules) instead of stripping formatting
+---
+### v0.9.2
+
+- Remove bundled Bun binary from npm package (now downloaded at install time for all platforms)
+- Package size reduced from 39.5 MB to 100 KB
+- Postinstall no longer fails npm install on Bun download failure (graceful fallback)
+- Removed `bun` from engines field (users no longer need Bun pre-installed)
+- Non-interactive modes (`--json`, `--csv`, etc.) work with just Node.js 20+
+
 ### v0.9.1
 
 - bug fix TUI layout issues on small terminals

package/bin/ghfind.js

@@ -3,9 +3,9 @@
  * ghfind — npm bin entry point.
  * Requires Node.js >= 20 or Bun.
  *
- * Uses the bundled Bun binary (vendor/bun.exe) to run the TypeScript source
- * directly, so users don't need to install Bun separately. Falls back to
- * the bundled dist/cli.js if present, or system Bun/Node.
+ * Strategy 1: Use a Bun binary from vendor/ (downloaded by postinstall) to
+ *   run TypeScript source directly. Strategy 2: Fall back to the bundled
+ *   dist/cli.js with Node.js (works for non-interactive modes).
  */
 import { existsSync } from "fs";
 import { spawnSync } from "child_process";

package/dist/cli.js

@@ -490,7 +490,8 @@ var SearchModule = class _SearchModule {
       query.raw,
       options.sort,
       String(options.limit),
-      String(options.page ?? 1)
+      String(options.page ?? 1),
+      options.trendingSince ?? "none"
     );
     const cached = _SearchModule.cache.get(cacheKey);
     if (cached) {
@@ -1133,6 +1134,35 @@ async function runInitWizard() {
   console.log("");
 }
 
+// src/compare.ts
+function buildComparisonTable(repos) {
+  if (repos.length < 2) return "Select at least 2 repos to compare (press c to add).";
+  const rows = [];
+  const names = repos.map((r) => r.fullName);
+  rows.push({ label: "Stars", values: repos.map((r) => `\u2605 ${r.stars.toLocaleString()}`) });
+  rows.push({ label: "Forks", values: repos.map((r) => r.forks.toLocaleString()) });
+  rows.push({ label: "Language", values: repos.map((r) => r.language ?? "\u2014") });
+  rows.push({ label: "Created", values: repos.map((r) => r.createdAt?.slice(0, 7) ?? "\u2014") });
+  rows.push({ label: "Updated", values: repos.map((r) => r.updatedAt?.slice(0, 10) ?? "\u2014") });
+  rows.push({ label: "Topics", values: repos.map((r) => (r.topics?.slice(0, 5).join(", ") ?? "\u2014") || "\u2014") });
+  rows.push({ label: "Description", values: repos.map((r) => r.description?.slice(0, 50) ?? "\u2014") });
+  rows.push({ label: "URL", values: repos.map((r) => r.url || "\u2014") });
+  const colW = Math.max(35, ...names.map((n) => n.length));
+  const header = ["".padEnd(14), ...names.map((n) => n.padEnd(colW))];
+  const sep = ["".padEnd(14, "\u2500"), ...names.map(() => "".padEnd(colW, "\u2500"))];
+  const lines = [
+    "\u250C" + sep.map((s) => "\u2500" + s + "\u2500").join("\u252C") + "\u2510",
+    "\u2502" + header.map((h) => ` ${h} `).join("\u2502") + "\u2502",
+    "\u251C" + sep.map((s) => "\u2500" + s + "\u2500").join("\u253C") + "\u2524"
+  ];
+  for (const row of rows) {
+    const cells = [row.label.padEnd(14), ...row.values.map((v) => v.padEnd(colW))];
+    lines.push("\u2502" + cells.map((c) => ` ${c} `).join("\u2502") + "\u2502");
+  }
+  lines.push("\u2514" + sep.map((s) => "\u2500" + s + "\u2500").join("\u2534") + "\u2518");
+  return lines.join("\n");
+}
+
 // src/cli.ts
 import { readFileSync as readFileSync3 } from "fs";
 import { join as join3, dirname as dirname2 } from "path";
@@ -1546,32 +1576,175 @@ function buildDeepDiveText(data) {
   ].join("\n");
 }
 
-// src/compare.ts
-function buildComparisonTable(repos) {
-  if (repos.length < 2) return "Select at least 2 repos to compare (press c to add).";
-  const rows = [];
-  const names = repos.map((r) => r.fullName);
-  rows.push({ label: "Stars", values: repos.map((r) => `\u2605 ${r.stars.toLocaleString()}`) });
-  rows.push({ label: "Forks", values: repos.map((r) => r.forks.toLocaleString()) });
-  rows.push({ label: "Language", values: repos.map((r) => r.language ?? "\u2014") });
-  rows.push({ label: "Created", values: repos.map((r) => r.createdAt?.slice(0, 7) ?? "\u2014") });
-  rows.push({ label: "Updated", values: repos.map((r) => r.updatedAt?.slice(0, 10) ?? "\u2014") });
-  rows.push({ label: "Topics", values: repos.map((r) => (r.topics?.slice(0, 3).join(", ") ?? "\u2014") || "\u2014") });
-  const colW = Math.max(15, ...names.map((n) => n.length));
-  const valW = Math.max(8, ...rows.flatMap((r) => r.values.map((v) => v.length)));
-  const header = ["".padEnd(14), ...names.map((n) => n.padEnd(colW))];
-  const sep = ["".padEnd(14, "\u2500"), ...names.map(() => "".padEnd(colW, "\u2500"))];
-  const lines = [
-    "\u250C" + sep.map((s) => "\u2500" + s + "\u2500").join("\u252C") + "\u2510",
-    "\u2502" + header.map((h) => ` ${h} `).join("\u2502") + "\u2502",
-    "\u251C" + sep.map((s) => "\u2500" + s + "\u2500").join("\u253C") + "\u2524"
-  ];
-  for (const row of rows) {
-    const cells = [row.label.padEnd(14), ...row.values.map((v) => v.padEnd(colW))];
-    lines.push("\u2502" + cells.map((c) => ` ${c} `).join("\u2502") + "\u2502");
+// src/markdown-render.ts
+function renderMarkdown(md, opts = {}) {
+  const width = opts.width ?? 80;
+  const lines = md.split("\n");
+  const out = [];
+  let inCodeBlock = false;
+  let codeLang = "";
+  let codeLines = [];
+  let inTable = false;
+  let tableRows = [];
+  function flushCode() {
+    if (codeLines.length === 0) return;
+    const maxLen = Math.max(...codeLines.map((l) => l.length), codeLang.length);
+    const barW = Math.min(maxLen + 4, width - 2);
+    out.push("\u250C" + "\u2500".repeat(barW) + "\u2510");
+    if (codeLang) out.push("\u2502 " + codeLang.padEnd(barW - 1) + "\u2502");
+    for (const cl of codeLines) {
+      out.push("\u2502 " + cl.padEnd(barW - 1) + "\u2502");
+    }
+    out.push("\u2514" + "\u2500".repeat(barW) + "\u2518");
+    out.push("");
+    codeLines = [];
+    codeLang = "";
+  }
+  function flushTable() {
+    if (tableRows.length === 0) return;
+    const dataRows = tableRows.filter(
+      (r) => !r.every((c) => /^[\s\-:|]+$/.test(c))
+    );
+    if (dataRows.length === 0) {
+      tableRows = [];
+      return;
+    }
+    const colCount = Math.max(...dataRows.map((r) => r.length));
+    const colW = [];
+    for (let ci = 0; ci < colCount; ci++) {
+      colW.push(
+        Math.max(
+          3,
+          ...dataRows.map((r) => (r[ci] ?? "").length)
+        )
+      );
+    }
+    const totalW = colW.reduce((a, b) => a + b, 0) + colCount * 3 - 1;
+    if (totalW > width) {
+      for (const row of dataRows) {
+        out.push("  " + row.map((c) => c.trim()).join(" \u2502 "));
+      }
+    } else {
+      const sep = "\u250C" + colW.map((w) => "\u2500".repeat(w + 2)).join("\u252C") + "\u2510";
+      const mid = "\u251C" + colW.map((w) => "\u2500".repeat(w + 2)).join("\u253C") + "\u2524";
+      const end = "\u2514" + colW.map((w) => "\u2500".repeat(w + 2)).join("\u2534") + "\u2518";
+      out.push(sep);
+      dataRows.forEach((row, i) => {
+        const cells = colW.map((w, ci) => (row[ci] ?? "").trim().padEnd(w));
+        out.push("\u2502 " + cells.map((c) => ` ${c} `).join("\u2502") + "\u2502");
+        if (i === 0) out.push(mid);
+      });
+      out.push(end);
+    }
+    out.push("");
+    tableRows = [];
+  }
+  function renderInline(line) {
+    line = line.replace(/\*\*(.+?)\*\*/g, "$1");
+    line = line.replace(/\*([^*]+?)\*/g, "$1");
+    line = line.replace(/`([^`]+)`/g, "\u27E8$1\u27E9");
+    line = line.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
+    line = line.replace(/!\[([^\]]*)\]\([^)]+\)/g, "\u{1F5BC} $1");
+    return line;
+  }
+  function wrapLine(line, maxW) {
+    if (line.length <= maxW) return [line];
+    const parts = [];
+    let remaining = line;
+    while (remaining.length > maxW) {
+      let breakAt = maxW;
+      const spaceIdx = remaining.lastIndexOf(" ", maxW);
+      if (spaceIdx > maxW / 2) breakAt = spaceIdx;
+      parts.push(remaining.slice(0, breakAt));
+      remaining = remaining.slice(breakAt).replace(/^ /, "");
+    }
+    if (remaining) parts.push(remaining);
+    return parts;
+  }
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    if (/^```/.test(line)) {
+      if (inCodeBlock) {
+        flushCode();
+        inCodeBlock = false;
+      } else {
+        inCodeBlock = true;
+        codeLang = line.slice(3).trim();
+      }
+      continue;
+    }
+    if (inCodeBlock) {
+      codeLines.push(line);
+      continue;
+    }
+    if (line.includes("|")) {
+      const cells = line.split("|").map((c) => c.trim()).filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+      if (cells.length >= 2) {
+        inTable = true;
+        tableRows.push(cells);
+        continue;
+      }
+    } else if (inTable) {
+      flushTable();
+      inTable = false;
+    }
+    if (/^(\s*[-*_]){3,}\s*$/.test(line)) {
+      out.push("\u2500".repeat(Math.min(width, 40)));
+      out.push("");
+      continue;
+    }
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = renderInline(headingMatch[2]);
+      const prefix = "\u2588 ".repeat(level);
+      out.push("");
+      out.push(prefix + text);
+      out.push("");
+      continue;
+    }
+    const bqMatch = line.match(/^>\s?(.*)/);
+    if (bqMatch) {
+      const inner = renderInline(bqMatch[1]);
+      for (const wl of wrapLine(inner, width - 4)) {
+        out.push("\u2502 " + wl);
+      }
+      continue;
+    }
+    const ulMatch = line.match(/^(\s*)[-*+]\s+(.*)/);
+    if (ulMatch) {
+      const indent = ulMatch[1].length;
+      const depth = Math.floor(indent / 2);
+      const prefix = "  ".repeat(depth) + "\u2022 ";
+      const inner = renderInline(ulMatch[2]);
+      for (const wl of wrapLine(inner, width - prefix.length)) {
+        out.push(prefix + wl);
+      }
+      continue;
+    }
+    const olMatch = line.match(/^(\s*)\d+\.\s+(.*)/);
+    if (olMatch) {
+      const indent = olMatch[1].length;
+      const depth = Math.floor(indent / 2);
+      const prefix = "  ".repeat(depth) + "\u25E6 ";
+      const inner = renderInline(olMatch[2]);
+      for (const wl of wrapLine(inner, width - prefix.length)) {
+        out.push(prefix + wl);
+      }
+      continue;
+    }
+    if (line.trim() === "") {
+      out.push("");
+      continue;
+    }
+    const rendered = renderInline(line);
+    for (const wl of wrapLine(rendered, width)) {
+      out.push(wl);
+    }
   }
-  lines.push("\u2514" + sep.map((s) => "\u2500" + s + "\u2500").join("\u2534") + "\u2518");
-  return lines.join("\n");
+  if (inCodeBlock) flushCode();
+  if (inTable) flushTable();
+  return out.join("\n");
 }
 
 // src/explore.ts
@@ -2134,27 +2307,27 @@ async function launchBrowser(theme_override) {
   for (let i = 0; i < landingOptions.length; i++) {
     const opt = landingOptions[i];
     const card = new BoxRenderable3(renderer, {
-      flexDirection: "row",
-      height: 1,
+      flexDirection: "column",
+      height: 5,
       width: "60%",
       marginTop: 1,
-      backgroundColor: void 0,
+      border: true,
       borderColor: i === 0 ? colors.accent : colors.border,
-      borderWidth: 1,
       paddingX: 1,
-      alignItems: "center",
       focusable: false
     });
     landingCards.push(card);
     landingBox.add(card);
+    const spacerTop = new TextRenderable3(renderer, { content: "", height: 1 });
     const titleLine = new TextRenderable3(renderer, {
       content: opt.title,
       color: i === 0 ? colors.accent : colors.text,
-      backgroundColor: void 0,
-      height: 1,
-      flexGrow: 1
+      height: 1
     });
+    const spacerBot = new TextRenderable3(renderer, { content: "", height: 1 });
+    card.add(spacerTop);
     card.add(titleLine);
+    card.add(spacerBot);
   }
   const landingHint = new TextRenderable3(renderer, {
     content: "   \u2191\u2193 Navigate  \u21E9 Select  [?]help  [q]uit",
@@ -2176,38 +2349,12 @@ async function launchBrowser(theme_override) {
   }
   function updateLandingCards() {
     for (let i = 0; i < landingCards.length; i++) {
-      const opt = landingOptions[i];
       const isSel = i === landingSelected;
-      landingCards[i].backgroundColor = isSel ? colors.selectionBg : colors.surface;
       landingCards[i].borderColor = isSel ? colors.accent : colors.border;
-      landingCards[i].borderWidth = isSel ? 1 : 0;
       const children = landingCards[i].children ?? [];
-      if (children[0]) {
-        const iconCol = children[0];
-        const iconChildren = iconCol.children ?? [];
-        const iconTextChild = iconChildren[0];
-        if (iconTextChild) {
-          iconTextChild.color = isSel ? colors.accent : colors.text;
-          iconTextChild.backgroundColor = isSel ? colors.selectionBg : colors.surface;
-        }
-        const iconSpacerChild = iconChildren[1];
-        if (iconSpacerChild) {
-          iconSpacerChild.backgroundColor = isSel ? colors.selectionBg : colors.surface;
-        }
-      }
-      if (children[1]) {
-        const contentCol = children[1];
-        const contentChildren = contentCol.children ?? [];
-        const titleChild = contentChildren[0];
-        if (titleChild) {
-          titleChild.color = isSel ? colors.accent : colors.text;
-          titleChild.backgroundColor = isSel ? colors.selectionBg : colors.surface;
-        }
-        const descChild = contentChildren[1];
-        if (descChild) {
-          descChild.backgroundColor = isSel ? colors.selectionBg : colors.surface;
-        }
-        const hintChild = contentChildren[2];
+      const titleChild = children[1];
+      if (titleChild) {
+        titleChild.color = isSel ? colors.accent : colors.text;
       }
     }
   }
@@ -3290,8 +3437,8 @@ async function launchBrowser(theme_override) {
       if (!text) {
         readmeText.content = `  (no README found for ${repo.fullName})`;
       } else {
-        const stripped = text.replace(/```[\s\S]*?```/g, "[code block]").replace(/#{1,6}\s/g, "").replace(/\*\*(.+?)\*\*/g, "$1").replace(/\[(.+?)\]\(.+?\)/g, "$1").replace(/`([^`]+)`/g, "$1").split("\n").map((l) => l.trimEnd()).join("\n");
-        readmeText.content = stripped;
+        const termW = Math.max(40, (process.stdout.columns || 80) - 4);
+        readmeText.content = renderMarkdown(text, { width: termW });
       }
     } catch {
       readmeText.content = "  Failed to load README";
@@ -3525,6 +3672,7 @@ async function launchBrowser(theme_override) {
     searchBox.visible = false;
     toolbarText.visible = false;
     trendingTabBox.visible = true;
+    body.visible = true;
     renderTrendingTabs();
     resultsSelect.options = [
       { name: "  Loading trending...", description: "", value: null }
@@ -4074,18 +4222,28 @@ ${pack.description ?? ""}`;
         showLeaderMenu();
       }
       return;
-      if (key.name === "t" && !searchInput.focused) {
-        const current = config.theme;
-        const themes = listThemes();
-        const idx = themes.indexOf(current);
-        const next = themes[(idx + 1) % themes.length];
-        const nextTheme = loadTheme(next);
-        Object.assign(colors, nextTheme);
-        config.theme = next;
-        saveConfig(config);
-        renderer.requestRender();
-        return;
+    }
+    if (key.name === "t" && !searchInput.focused) {
+      const current = config.theme;
+      const themes = listThemes();
+      const idx = themes.indexOf(current);
+      const next = themes[(idx + 1) % themes.length];
+      const nextTheme = loadTheme(next);
+      Object.assign(colors, nextTheme);
+      config.theme = next;
+      saveConfig(config);
+      renderer.requestRender();
+      return;
+    }
+    if (key.name === "c" && !searchInput.focused) {
+      if (currentOverlay === "compare") {
+        showOverlay("none");
+      } else {
+        toggleCompareOnSelected();
+        refreshCompare();
+        showOverlay("compare");
       }
+      return;
     }
     if (key.name === "?" || key.name === "h" && key.ctrl) {
       showOverlay("help");
@@ -4236,7 +4394,8 @@ function parseArgs(args) {
     version: false,
     help: false,
     pkg: false,
-    registry: "npm"
+    registry: "npm",
+    compare: []
   };
   let queryParts = [];
   for (let i = 0; i < args.length; i++) {
@@ -4305,6 +4464,14 @@ function parseArgs(args) {
       case "--completion":
         flags.completion = args[++i];
         break;
+      case "--compare": {
+        const repos = [];
+        while (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+          repos.push(args[++i]);
+        }
+        flags.compare = repos;
+        break;
+      }
       default:
         if (!arg.startsWith("-")) queryParts.push(arg);
     }
@@ -4336,6 +4503,7 @@ Usage:
   ghfind <query> --format <fmt>    Format lines (urls|names|ssh-urls|clone-commands|ids)
   ghfind <query> --pipe <target>   Pipe to clone/open
   ghfind --trending --json         Trending repos as JSON
+  ghfind --compare <repo1> <repo2> Compare two+ repos side-by-side
   ghfind pkg <query> --json         Search npm packages, output JSON
   ghfind pkg <query>                Search npm packages, text list
   ghfind --watch <query>           Watch mode (poll every Ns)
@@ -4516,9 +4684,21 @@ async function runNonInteractive(flags, outputFormat) {
       if (outputFormat) {
         console.log(format(repos, outputFormat));
       }
+    },
+    compare: async (_ctx) => {
+      const search = createGitHubSearch(void 0, [flags.token ?? ""]);
+      const repos = [];
+      for (const fullName of flags.compare) {
+        const res = await search.search(
+          { keywords: [fullName], qualifiers: [], raw: fullName },
+          { limit: 1, sort: "stars", json: false, verbose: false, token: flags.token }
+        );
+        repos.push(...res.repos);
+      }
+      console.log(buildComparisonTable(repos));
     }
   };
-  const key = flags.trending && !flags.watch ? "trending" : flags.watch ? "watch" : flags.pipe ? "pipe" : flags.format ? "format" : "search";
+  const key = flags.compare.length > 0 ? "compare" : flags.trending && !flags.watch ? "trending" : flags.watch ? "watch" : flags.pipe ? "pipe" : flags.format ? "format" : "search";
   const ctx = buildSearchContext(flags);
   await handlers[key](ctx);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.1.1",
+  "version": "9.3.0",
   "description": "Terminal-native GitHub search — search, trending, bookmarks, history, deep-dive, compare, export, and more. All keyboard-driven, no browser needed.",
   "type": "module",
   "packageManager": "bun@1",
@@ -16,7 +16,6 @@
   "files": [
     "bin/",
     "dist/",
-    "vendor/",
     "src/",
     "scripts/",
     "completions/",
@@ -45,8 +44,7 @@
     "typescript": "^5.3.0"
   },
   "engines": {
-    "node": ">=20.0.0",
-    "bun": ">=1.0.0"
+    "node": ">=20.0.0"
   },
   "repository": {
     "type": "git",

package/scripts/postinstall.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * Postinstall script — ensures a Bun binary is available for ghfind.
+ * Postinstall script — downloads a Bun binary for ghfind's TUI.
  *
- * If vendor/bun or vendor/bun.exe already exists (bundled with the package),
- * this is a no-op. Otherwise, it attempts to download the correct binary
- * for the user's platform.
+ * If vendor/bun or vendor/bun.exe already exists, this is a no-op.
+ * Otherwise, it downloads the correct Bun binary for the user's platform.
+ * On failure, prints a warning and exits 0 so npm install still succeeds.
  */
 import { existsSync, mkdirSync, chmodSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
@@ -100,7 +100,10 @@ try {
 
   throw new Error("Bun binary not found in archive");
 } catch (err) {
-  console.error(`[ghfind] Failed to download Bun: ${err instanceof Error ? err.message : String(err)}`);
-  console.error("[ghfind] Install Bun manually: https://bun.sh/docs/install");
-  process.exit(1);
+  console.warn(`[ghfind] ⚠ Could not download Bun: ${err instanceof Error ? err.message : String(err)}`);
+  console.warn("[ghfind] The interactive TUI requires Bun. Install it manually:");
+  console.warn("[ghfind]   curl -fsSL https://bun.sh/install | bash");
+  console.warn("[ghfind]   # or: npm install -g bun");
+  console.warn("[ghfind] Non-interactive modes (--json, --csv, etc.) will still work with Node.js 20+.");
+  process.exit(0);
 }

package/src/cli.ts

@@ -15,6 +15,8 @@ import { launchPackageBrowser } from "./package-browser";
 import { format as formatOutput, exportToFile, pipeExec, type Format, type ExportFormat, type FormatLine } from "./output";
 import { runWatch } from "./watch";
 import { runInitWizard } from "./init";
+import { buildComparisonTable } from "./compare";
+import type { Repo } from "./types";
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -46,6 +48,7 @@ interface CLIFlags {
   pkg: boolean;
   theme?: string;
   registry: string;
+  compare: string[];  // repo fullNames to compare
 }
 
 function parseArgs(args: string[]): CLIFlags {
@@ -67,6 +70,7 @@ function parseArgs(args: string[]): CLIFlags {
     help: false,
     pkg: false,
     registry: "npm",
+    compare: [],
   };
 
   let queryParts: string[] = [];
@@ -100,6 +104,15 @@ function parseArgs(args: string[]): CLIFlags {
       case "--registry": flags.registry = args[++i] ?? "npm"; break;
       case "--theme": flags.theme = args[++i] ?? "tokyo-night"; break;
       case "--completion": flags.completion = args[++i]; break;
+      case "--compare": {
+        // Collect repo names until next flag
+        const repos: string[] = [];
+        while (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+          repos.push(args[++i]);
+        }
+        flags.compare = repos;
+        break;
+      }
       default:
         if (!arg.startsWith("-")) queryParts.push(arg);
     }
@@ -136,6 +149,7 @@ Usage:
   ghfind <query> --format <fmt>    Format lines (urls|names|ssh-urls|clone-commands|ids)
   ghfind <query> --pipe <target>   Pipe to clone/open
   ghfind --trending --json         Trending repos as JSON
+  ghfind --compare <repo1> <repo2> Compare two+ repos side-by-side
   ghfind pkg <query> --json         Search npm packages, output JSON
   ghfind pkg <query>                Search npm packages, text list
   ghfind --watch <query>           Watch mode (poll every Ns)
@@ -328,10 +342,23 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
         console.log(formatOutput(repos, outputFormat));
       }
     },
+    compare: async (_ctx) => {
+      const search = createGitHubSearch(undefined, [flags.token ?? ""]);
+      const repos: Repo[] = [];
+      for (const fullName of flags.compare) {
+        const res = await search.search(
+          { keywords: [fullName], qualifiers: [], raw: fullName },
+          { limit: 1, sort: "stars", json: false, verbose: false, token: flags.token },
+        );
+        repos.push(...res.repos);
+      }
+      console.log(buildComparisonTable(repos));
+    },
   };
 
   // Determine which handler to run
-  const key = flags.trending && !flags.watch ? "trending"
+  const key = flags.compare.length > 0 ? "compare"
+    : flags.trending && !flags.watch ? "trending"
     : flags.watch ? "watch"
     : flags.pipe ? "pipe"
     : flags.format ? "format"

package/src/compare.ts

@@ -20,11 +20,12 @@ export function buildComparisonTable(repos: Repo[]): string {
   rows.push({ label: "Language", values: repos.map((r) => r.language ?? "—") });
   rows.push({ label: "Created", values: repos.map((r) => r.createdAt?.slice(0, 7) ?? "—") });
   rows.push({ label: "Updated", values: repos.map((r) => r.updatedAt?.slice(0, 10) ?? "—") });
-  rows.push({ label: "Topics", values: repos.map((r) => (r.topics?.slice(0, 3).join(", ") ?? "—") || "—") });
+  rows.push({ label: "Topics", values: repos.map((r) => (r.topics?.slice(0, 5).join(", ") ?? "—") || "—") });
+  rows.push({ label: "Description", values: repos.map((r) => (r.description?.slice(0, 50) ?? "—")) });
+  rows.push({ label: "URL", values: repos.map((r) => r.url || "—") });
 
   // Calculate the max width for each column
-  const colW = Math.max(15, ...names.map((n) => n.length));
-  const valW = Math.max(8, ...rows.flatMap((r) => r.values.map((v) => v.length)));
+  const colW = Math.max(35, ...names.map((n) => n.length));
 
   // Header row
   const header = ["".padEnd(14), ...names.map((n) => n.padEnd(colW))];