github-search-cli 9.2.1 → 9.4.0

package/dist/cli.js

@@ -1,4 +1,6 @@
 import {
+  cacheDir,
+  configPath,
   loadConfig,
   saveConfig,
   stateDir
@@ -894,6 +896,351 @@ async function launchPackageBrowser() {
   renderer.requestRender();
 }
 
+// src/doctor.ts
+import { existsSync, readFileSync, mkdirSync } from "fs";
+import { spawnSync } from "child_process";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir, platform, arch } from "os";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var PKG_DIR = join(__dirname, "..");
+var results = [];
+function add(status, label, detail) {
+  results.push({ status, label, detail });
+}
+function run(cmd, args) {
+  try {
+    const res = spawnSync(cmd, args, { encoding: "utf8", timeout: 15e3 });
+    return {
+      status: res.status,
+      stdout: res.stdout ?? "",
+      stderr: res.stderr ?? ""
+    };
+  } catch {
+    return { status: null, stdout: "", stderr: "" };
+  }
+}
+function hasSystemBun() {
+  const res = run("bun", ["--version"]);
+  return res.status === 0 ? { ok: true, version: res.stdout.trim() } : { ok: false };
+}
+function bundledBunPath() {
+  return join(PKG_DIR, "vendor", platform() === "win32" ? "bun.exe" : "bun");
+}
+function bunRuns(bin) {
+  const res = run(bin, ["--version"]);
+  if (res.status !== 0) return { ok: false };
+  return { ok: true, version: res.stdout.trim() };
+}
+function detectLibc() {
+  if (platform() !== "linux") return "unknown";
+  try {
+    const osRelease = readFileSync("/etc/os-release", "utf8");
+    if (/alpine|musl/i.test(osRelease)) return "musl";
+  } catch {
+  }
+  const ldd = run("ldd", ["--version"]);
+  const out = `${ldd.stdout}${ldd.stderr}`;
+  if (/musl/i.test(out)) return "musl";
+  if (/glibc|GNU libc/i.test(out)) return "glibc";
+  return "unknown";
+}
+async function checkRuntime() {
+  const runningOnBun = process.versions.bun !== void 0;
+  const runtime = runningOnBun ? `Bun ${process.versions.bun}` : `Node ${process.version}`;
+  add(
+    runningOnBun ? "PASS" : "WARN",
+    "Runtime",
+    `Running on ${runtime}. The interactive TUI needs Bun.`
+  );
+}
+function checkBundledBun() {
+  const path = bundledBunPath();
+  if (!existsSync(path)) {
+    add(
+      "WARN",
+      "Bundled Bun",
+      `Not found (${path}). Run \`npm install\` or install Bun manually.`
+    );
+    return { ok: false };
+  }
+  const check = bunRuns(path);
+  if (check.ok) {
+    add("PASS", "Bundled Bun", `${path} (v${check.version})`);
+    return { ok: true };
+  }
+  const libc = detectLibc();
+  const hint = libc === "musl" ? "Installed Bun is the glibc build, but this system uses musl." : libc === "glibc" ? "Installed Bun is the musl build, but this system uses glibc." : "The bundled binary does not launch.";
+  add("FAIL", "Bundled Bun", `${path} does not launch. ${hint}`);
+  return { ok: false };
+}
+function checkSystemBun(bundledOk) {
+  const sys = hasSystemBun();
+  if (sys.ok) {
+    add("PASS", "System Bun", `Found \`bun\` on PATH (v${sys.version}).`);
+  } else if (bundledOk) {
+    add(
+      "WARN",
+      "System Bun",
+      "No `bun` on PATH. Bundled Bun is working, so this is only a fallback."
+    );
+  } else {
+    add(
+      "FAIL",
+      "System Bun",
+      "No `bun` on PATH. Install it: curl -fsSL https://bun.sh/install | bash"
+    );
+  }
+}
+function checkNodeVersion() {
+  const major = parseInt(process.version.replace(/^v/, "").split(".")[0], 10);
+  if (Number.isNaN(major) || major >= 20) {
+    add("PASS", "Node version", `Node ${process.version} (>= 20 required)`);
+  } else {
+    add(
+      "FAIL",
+      "Node version",
+      `Node ${process.version} is too old (>= 20 required)`
+    );
+  }
+}
+function checkBuildOutput() {
+  const dist = join(PKG_DIR, "dist", "cli.js");
+  if (existsSync(dist)) {
+    add("PASS", "Build output", `${dist}`);
+  } else {
+    add(
+      "WARN",
+      "Build output",
+      "dist/cli.js not found. Run `npm run build` (Node-only fallback needs it)."
+    );
+  }
+}
+function checkSource() {
+  const src = join(PKG_DIR, "src", "cli.ts");
+  if (existsSync(src)) {
+    add("PASS", "Source", `${src}`);
+  } else {
+    add("FAIL", "Source", "src/cli.ts not found. Reinstall the package.");
+  }
+}
+function checkTuiBackend() {
+  const isTTY = process.stdout.isTTY && process.stdin.isTTY;
+  add(
+    isTTY ? "PASS" : "WARN",
+    "Terminal (TTY)",
+    isTTY ? "stdin/stdout are TTYs \u2014 TUI can render." : "stdin/stdout are not TTYs \u2014 the TUI cannot render (piped/non-interactive)."
+  );
+}
+function checkConfig() {
+  const path = configPath();
+  if (!existsSync(path)) {
+    add(
+      "WARN",
+      "Config",
+      `Not found (${path}). Run \`ghfind init\` or it will use defaults.`
+    );
+    return;
+  }
+  try {
+    const raw = readFileSync(path, "utf-8");
+    JSON.parse(raw);
+    add("PASS", "Config", `${path} (valid JSON)`);
+  } catch (err) {
+    add(
+      "FAIL",
+      "Config",
+      `${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function checkGithubToken() {
+  const config = loadConfig();
+  const token = config.githubToken || process.env.GITHUB_TOKEN;
+  if (token) {
+    const preview = token.slice(0, 7);
+    add("PASS", "GitHub token", `Configured (${preview}\u2026).`);
+  } else {
+    add(
+      "WARN",
+      "GitHub token",
+      "No token found. Unauthenticated requests hit lower rate limits."
+    );
+  }
+}
+function checkDirs() {
+  for (const [label, dir] of [
+    ["State dir", stateDir()],
+    ["Cache dir", cacheDir()]
+  ]) {
+    try {
+      mkdirSync(dir, { recursive: true });
+      add("PASS", label, dir);
+    } catch (err) {
+      add(
+        "FAIL",
+        label,
+        `${dir} not writable: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+}
+function printReport() {
+  const colors2 = (s, n) => {
+    const code = n === "PASS" ? "\x1B[32m" : n === "WARN" ? "\x1B[33m" : "\x1B[31m";
+    return `${code}${s}\x1B[0m`;
+  };
+  console.log("\n  ghfind doctor \u2014 environment diagnostics");
+  console.log(`  ${platform()} ${arch} \xB7 ${homedir()}`);
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  for (const r of results) {
+    console.log(
+      `  ${colors2(r.status.padEnd(4), r.status)}  ${r.label}: ${r.detail}`
+    );
+  }
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  const fails = results.filter((r) => r.status === "FAIL").length;
+  const warns = results.filter((r) => r.status === "WARN").length;
+  if (fails === 0 && warns === 0) {
+    console.log("  All checks passed.");
+  } else if (fails === 0) {
+    console.log(
+      `  ${warns} warning(s) \u2014 ghfind should work, but review the items above.`
+    );
+  } else {
+    console.log(
+      `  ${fails} failed check(s). Resolve these before running the TUI.`
+    );
+  }
+  console.log("");
+}
+async function runDoctor() {
+  await checkRuntime();
+  const bundled = checkBundledBun();
+  checkSystemBun(bundled.ok);
+  checkNodeVersion();
+  checkBuildOutput();
+  checkSource();
+  checkTuiBackend();
+  checkConfig();
+  checkGithubToken();
+  checkDirs();
+  printReport();
+  const hasFail = results.some((r) => r.status === "FAIL");
+  process.exitCode = hasFail ? 1 : 0;
+}
+
+// src/error-report.ts
+import { platform as osPlatform, arch as osArch, version as nodeVersion, versions as nodeVersions } from "process";
+import { spawn } from "child_process";
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join2, dirname as dirname2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var REPO = "codersdfs/search-cli";
+var NEW_ISSUE_URL = `https://github.com/${REPO}/issues/new`;
+function getPackageVersion() {
+  try {
+    const __dirname5 = dirname2(fileURLToPath2(import.meta.url));
+    const pkgPath = join2(__dirname5, "..", "package.json");
+    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function runtimeName() {
+  const bunVer = nodeVersions.bun;
+  return bunVer ? `Bun ${bunVer}` : `Node ${nodeVersion}`;
+}
+function formatErrorBody(err, context) {
+  const e = err instanceof Error ? err : new Error(String(err));
+  const stack = (e.stack ?? "(no stack)").replace(/\u001b\[[0-9;]*m/g, "");
+  const message = (e.message || "(no message)").slice(0, 500);
+  const cmd = `${context.command} ${context.argv.join(" ")}`.trim();
+  const ghfindVersion = getPackageVersion();
+  return [
+    "## What happened",
+    "",
+    "```",
+    message,
+    "```",
+    "",
+    "## Command",
+    "",
+    "```",
+    cmd,
+    "```",
+    "",
+    "## Stack trace",
+    "",
+    "```",
+    stack,
+    "```",
+    "",
+    "## Environment",
+    "",
+    `- ghfind: v${ghfindVersion}`,
+    `- runtime: ${runtimeName()}`,
+    `- platform: ${osPlatform} ${osArch}`,
+    "",
+    "## Notes",
+    "",
+    "Add anything else that might help (network state, what you were doing, etc.)."
+  ].join("\n");
+}
+function buildIssueUrl(err, context) {
+  const e = err instanceof Error ? err : new Error(String(err));
+  const title = e.message.slice(0, 80).replace(/[\r\n]+/g, " ");
+  const body = formatErrorBody(err, context);
+  const params = new URLSearchParams({
+    title: `[bug] ${title || "Unhandled error"}`,
+    body,
+    labels: "bug"
+  });
+  return `${NEW_ISSUE_URL}?${params.toString()}`;
+}
+function tryOpenUrl(url) {
+  try {
+    const p = osPlatform;
+    if (typeof Bun !== "undefined") {
+      if (p === "win32") Bun.spawn(["cmd", "/c", "start", "", url]);
+      else if (p === "darwin") Bun.spawn(["open", url]);
+      else Bun.spawn(["xdg-open", url]);
+      return true;
+    }
+    const cmd = p === "win32" ? "cmd" : p === "darwin" ? "open" : "xdg-open";
+    const args = p === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+function reportError(err, context = {
+  command: "ghfind",
+  argv: process.argv.slice(2)
+}) {
+  const url = buildIssueUrl(err, context);
+  console.error("");
+  console.error("  \u26A0  ghfind encountered an unexpected error.");
+  console.error("");
+  console.error("  Help us fix it by opening a bug report with the");
+  console.error("  details pre-filled. Your browser will open the new-issue");
+  console.error("  page; review and submit (or close the tab to skip).");
+  console.error("");
+  const opened = tryOpenUrl(url);
+  if (opened) {
+    console.error("  \u2192 Opened: " + url);
+  } else {
+    console.error("  Copy this URL to file a bug report:");
+    console.error("");
+    console.error("    " + url);
+  }
+  console.error("");
+  return url;
+}
+
 // src/output.ts
 import { writeFileSync } from "fs";
 var FORMATS = /* @__PURE__ */ new Map([
@@ -1027,6 +1374,221 @@ async function runWatch(opts, onChange, onError) {
   }
 }
 
+// src/storage.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, appendFileSync, unlinkSync } from "fs";
+import { join as join3 } from "path";
+function ensureDir() {
+  mkdirSync2(stateDir(), { recursive: true });
+}
+function readJSON(filename, fallback) {
+  ensureDir();
+  try {
+    return JSON.parse(readFileSync3(join3(stateDir(), filename), "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+function writeJSON(filename, data) {
+  ensureDir();
+  writeFileSync2(join3(stateDir(), filename), JSON.stringify(data, null, 2));
+}
+function appendJSONL(filename, obj) {
+  ensureDir();
+  try {
+    appendFileSync(join3(stateDir(), filename), JSON.stringify(obj) + "\n", "utf-8");
+  } catch {
+  }
+}
+function readJSONL(filename) {
+  ensureDir();
+  try {
+    const raw = readFileSync3(join3(stateDir(), filename), "utf-8").trim();
+    if (!raw) return [];
+    return raw.split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  } catch {
+    return [];
+  }
+}
+function writeRaw(filename, data) {
+  ensureDir();
+  writeFileSync2(join3(stateDir(), filename), data);
+}
+function debugLog(msg) {
+  if (!process.env.DEBUG) return;
+  try {
+    appendFileSync(join3(stateDir(), "ghfind-debug.log"), `[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}
+`, "utf-8");
+  } catch {
+  }
+}
+
+// src/bookmarks.ts
+var BOOKMARK_FILE = "bookmarks.json";
+function loadRaw() {
+  return readJSON(BOOKMARK_FILE, []);
+}
+function saveRaw(bookmarks) {
+  writeJSON(BOOKMARK_FILE, bookmarks);
+}
+function getBookmarks() {
+  return loadRaw().sort((a, b) => b.savedAt - a.savedAt);
+}
+function toggleBookmark(repo, tags = []) {
+  const bookmarks = loadRaw();
+  const idx = bookmarks.findIndex((b) => b.repo.fullName === repo.fullName);
+  if (idx >= 0) {
+    bookmarks.splice(idx, 1);
+    saveRaw(bookmarks);
+    return false;
+  }
+  bookmarks.push({ repo, savedAt: Date.now(), tags });
+  saveRaw(bookmarks);
+  return true;
+}
+function removeBookmark(fullName) {
+  const bookmarks = loadRaw().filter((b) => b.repo.fullName !== fullName);
+  saveRaw(bookmarks);
+}
+function getLastSeen(fullName) {
+  return loadRaw().find((b) => b.repo.fullName === fullName)?.lastSeenAt ?? 0;
+}
+function markSeen(fullName) {
+  const bookmarks = loadRaw();
+  const bm = bookmarks.find((b) => b.repo.fullName === fullName);
+  if (bm) {
+    bm.lastSeenAt = Date.now();
+    saveRaw(bookmarks);
+  }
+}
+
+// src/notifications.ts
+var nextId = 1;
+var notifs = [];
+var MAX_NOTIFS = 50;
+var FILE = "notifications.json";
+function load() {
+  notifs = readJSON(FILE, []);
+  nextId = Math.max(...notifs.map((n) => n.id), 0) + 1;
+}
+function save() {
+  writeJSON(FILE, notifs);
+}
+function addNotification(type, message) {
+  if (notifs.length === 0) load();
+  const n = { id: nextId++, type, icon: iconFor(type), message, timestamp: Date.now() };
+  notifs.unshift(n);
+  if (notifs.length > MAX_NOTIFS) notifs = notifs.slice(0, MAX_NOTIFS);
+  save();
+  return n;
+}
+function iconFor(type) {
+  switch (type) {
+    case "info":
+      return "\u2139";
+    case "warning":
+      return "\u26A0";
+    case "rate-limit":
+      return "\u{1F6AB}";
+    case "watch-change":
+      return "\u{1F514}";
+    case "upgrade":
+      return "\u{1F4E6}";
+    case "release":
+      return "\u{1F680}";
+  }
+}
+function getNotifications() {
+  if (notifs.length === 0) load();
+  return [...notifs];
+}
+function dismissNotification(id) {
+  notifs = notifs.filter((n) => n.id !== id);
+  save();
+}
+function dismissAll() {
+  notifs = [];
+  save();
+}
+
+// src/releases.ts
+var RELEASES_FILE = "release-cache.json";
+var PER_REPO = 5;
+function loadCache() {
+  return readJSON(RELEASES_FILE, {});
+}
+function saveCache(cache) {
+  writeJSON(RELEASES_FILE, cache);
+}
+function toTracked(raw) {
+  return raw.filter((r) => r.draft !== true).map((r) => ({
+    id: r.id,
+    tagName: r.tag_name,
+    name: r.name || r.tag_name,
+    url: r.html_url,
+    publishedAt: r.published_at || "",
+    prerelease: r.prerelease === true
+  }));
+}
+async function fetchReleases(fullName, etag, token) {
+  const headers = { Accept: "application/vnd.github+json" };
+  if (etag) headers["If-None-Match"] = etag;
+  if (token) headers["Authorization"] = `Bearer ${token}`;
+  const res = await fetch(`https://api.github.com/repos/${fullName}/releases?per_page=${PER_REPO}`, { headers });
+  if (res.status === 304 || !res.ok) return { status: res.status };
+  return {
+    status: 200,
+    etag: res.headers.get("etag") ?? void 0,
+    releases: toTracked(await res.json())
+  };
+}
+async function checkReleases(opts = {}) {
+  const bookmarks = getBookmarks();
+  const cache = loadCache();
+  const config = loadConfig();
+  const token = opts.token ?? config.githubToken ?? process.env.GITHUB_TOKEN;
+  const results2 = [];
+  for (const bm of bookmarks) {
+    try {
+      const prev = cache[bm.repo.fullName];
+      const lastSeen = getLastSeen(bm.repo.fullName);
+      const isNew = (r) => !r.publishedAt || new Date(r.publishedAt).getTime() > lastSeen;
+      const { status, etag, releases } = await fetchReleases(bm.repo.fullName, prev?.etag, token);
+      if (status === 304 && prev) {
+        results2.push({ fullName: bm.repo.fullName, newReleases: prev.releases.filter(isNew) });
+        continue;
+      }
+      if (status !== 200 || !releases) {
+        results2.push({ fullName: bm.repo.fullName, newReleases: [], error: `HTTP ${status}` });
+        continue;
+      }
+      cache[bm.repo.fullName] = { checkedAt: Date.now(), etag, releases };
+      results2.push({ fullName: bm.repo.fullName, newReleases: releases.filter(isNew) });
+    } catch (err) {
+      results2.push({ fullName: bm.repo.fullName, newReleases: [], error: err.message });
+    }
+  }
+  saveCache(cache);
+  return results2;
+}
+async function checkAndNotify(opts = {}) {
+  const results2 = await checkReleases(opts);
+  for (const r of results2) {
+    for (const rel of r.newReleases) {
+      addNotification(
+        "release",
+        `${r.fullName} released ${rel.tagName}${rel.prerelease ? " [pre]" : ""}`
+      );
+    }
+    if (r.newReleases.length > 0) markSeen(r.fullName);
+  }
+  return results2;
+}
+function allCachedReleases() {
+  const cache = loadCache();
+  const bookmarks = getBookmarks();
+  return Object.entries(cache).filter(([fullName]) => bookmarks.some((b) => b.repo.fullName === fullName)).flatMap(([fullName, s]) => s.releases.map((r) => ({ ...r, fullName }))).sort((a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime());
+}
+
 // src/init.ts
 import { createInterface } from "readline";
 
@@ -1128,8 +1690,8 @@ async function runInitWizard() {
   };
   if (token) config.githubToken = token;
   saveConfig(config);
-  const { configPath } = await import("./config-GNZOQRTH.js");
-  console.log(`  \u2713 Config saved to ${configPath()}`);
+  const { configPath: configPath2 } = await import("./config-GNZOQRTH.js");
+  console.log(`  \u2713 Config saved to ${configPath2()}`);
   console.log("  Run 'ghfind' to start browsing!");
   console.log("");
 }
@@ -1144,9 +1706,10 @@ function buildComparisonTable(repos) {
   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)));
+  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 = [
@@ -1163,9 +1726,9 @@ function buildComparisonTable(repos) {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join3, dirname as dirname2 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { readFileSync as readFileSync6 } from "fs";
+import { join as join6, dirname as dirname5 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
 
 // src/tui.ts
 import {
@@ -1218,7 +1781,8 @@ function buildHelpSections() {
       titleColor: "blue",
       rows: [
         { keys: "\u2191 \u2193 / j k", action: "Navigate menu cards" },
-        { keys: "Enter", action: "Select mode" },
+        { keys: "Enter", action: "Select mode / open Bookmarks" },
+        { keys: "b", action: "Jump straight to Bookmarks" },
         { keys: "? / h", action: "Toggle this help screen" },
         { keys: "q", action: "Quit" }
       ]
@@ -1240,6 +1804,9 @@ function buildHelpSections() {
       titleColor: "green",
       rows: [
         { keys: "Tab", action: "Auto-complete qualifier" },
+        { keys: "b", action: "Bookmark / unbookmark selected repo" },
+        { keys: "c", action: "Compare selected repo" },
+        { keys: "t", action: "Cycle theme" },
         { keys: "PageDown", action: "Next page of results" },
         { keys: "PageUp", action: "Scroll to top of results" }
       ]
@@ -1287,13 +1854,24 @@ function buildHelpSections() {
       ],
       note: "Navigate menu with \u2191 \u2193, select with Enter, back with \u2190 / Esc"
     },
+    {
+      title: " Bookmarks Page ",
+      titleColor: "green",
+      rows: [
+        { keys: "\u2191 \u2193 / j k", action: "Move selection" },
+        { keys: "Enter", action: "Open bookmark in browser" },
+        { keys: "d", action: "Remove bookmark" },
+        { keys: "Esc / \u2190", action: "Back to landing" }
+      ],
+      note: "A full page, not an overlay \u2014 Esc returns to the mode menu."
+    },
     {
       title: " Overlay Keys ",
       titleColor: "teal",
       rows: [
         { keys: "Esc / q", action: "Close any overlay" },
         { keys: "Enter", action: "Confirm selection / run action" },
-        { keys: "d", action: "Delete entry (history, bookmarks, saved)" },
+        { keys: "d", action: "Delete entry (history, saved)" },
         { keys: "\u2191 \u2193 / j k", action: "Navigate overlay list" },
         { keys: "\u2190 \u2192 / h l", action: "Navigate tabs / panels" }
       ]
@@ -1340,54 +1918,6 @@ function buildHelpSections() {
 }
 var HELP_KEYS_COLUMN = 24;
 
-// src/storage.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync as writeFileSync2, appendFileSync, unlinkSync } from "fs";
-import { join } from "path";
-function ensureDir() {
-  mkdirSync(stateDir(), { recursive: true });
-}
-function readJSON(filename, fallback) {
-  ensureDir();
-  try {
-    return JSON.parse(readFileSync(join(stateDir(), filename), "utf-8"));
-  } catch {
-    return fallback;
-  }
-}
-function writeJSON(filename, data) {
-  ensureDir();
-  writeFileSync2(join(stateDir(), filename), JSON.stringify(data, null, 2));
-}
-function appendJSONL(filename, obj) {
-  ensureDir();
-  try {
-    appendFileSync(join(stateDir(), filename), JSON.stringify(obj) + "\n", "utf-8");
-  } catch {
-  }
-}
-function readJSONL(filename) {
-  ensureDir();
-  try {
-    const raw = readFileSync(join(stateDir(), filename), "utf-8").trim();
-    if (!raw) return [];
-    return raw.split("\n").filter(Boolean).map((l) => JSON.parse(l));
-  } catch {
-    return [];
-  }
-}
-function writeRaw(filename, data) {
-  ensureDir();
-  writeFileSync2(join(stateDir(), filename), data);
-}
-function debugLog(msg) {
-  if (!process.env.DEBUG) return;
-  try {
-    appendFileSync(join(stateDir(), "ghfind-debug.log"), `[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}
-`, "utf-8");
-  } catch {
-  }
-}
-
 // src/history.ts
 var HISTORY_FILE = "history.jsonl";
 var MAX_ENTRIES = 500;
@@ -1424,34 +1954,6 @@ function rotateHistory() {
   writeRaw(HISTORY_FILE, trimmed.reverse().map((e) => JSON.stringify(e)).join("\n") + "\n");
 }
 
-// src/bookmarks.ts
-var BOOKMARK_FILE = "bookmarks.json";
-function loadRaw() {
-  return readJSON(BOOKMARK_FILE, []);
-}
-function saveRaw(bookmarks) {
-  writeJSON(BOOKMARK_FILE, bookmarks);
-}
-function getBookmarks() {
-  return loadRaw().sort((a, b) => b.savedAt - a.savedAt);
-}
-function toggleBookmark(repo, tags = []) {
-  const bookmarks = loadRaw();
-  const idx = bookmarks.findIndex((b) => b.repo.fullName === repo.fullName);
-  if (idx >= 0) {
-    bookmarks.splice(idx, 1);
-    saveRaw(bookmarks);
-    return false;
-  }
-  bookmarks.push({ repo, savedAt: Date.now(), tags });
-  saveRaw(bookmarks);
-  return true;
-}
-function removeBookmark(fullName) {
-  const bookmarks = loadRaw().filter((b) => b.repo.fullName !== fullName);
-  saveRaw(bookmarks);
-}
-
 // src/saved-searches.ts
 var SAVED_FILE = "saved-searches.json";
 function loadRaw2() {
@@ -1575,6 +2077,177 @@ function buildDeepDiveText(data) {
   ].join("\n");
 }
 
+// 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);
+    }
+  }
+  if (inCodeBlock) flushCode();
+  if (inTable) flushTable();
+  return out.join("\n");
+}
+
 // src/explore.ts
 async function fetchTopics() {
   const res = await fetch("https://api.github.com/search/topics?q=popular&per_page=30", {
@@ -1638,32 +2311,8 @@ var StatusManager = class {
   }
 };
 
-// src/notifications.ts
-var nextId = 1;
-var notifs = [];
-var FILE = "notifications.json";
-function load() {
-  notifs = readJSON(FILE, []);
-  nextId = Math.max(...notifs.map((n) => n.id), 0) + 1;
-}
-function save() {
-  writeJSON(FILE, notifs);
-}
-function getNotifications() {
-  if (notifs.length === 0) load();
-  return [...notifs];
-}
-function dismissNotification(id) {
-  notifs = notifs.filter((n) => n.id !== id);
-  save();
-}
-function dismissAll() {
-  notifs = [];
-  save();
-}
-
 // src/share.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 function formatShare(repo, format2) {
   switch (format2) {
     case "markdown":
@@ -1681,7 +2330,7 @@ async function copyToClipboard(text) {
     const p = process.platform;
     const cmd = p === "win32" ? ["clip"] : p === "darwin" ? ["pbcopy"] : await findLinuxClipCmd();
     if (!cmd) return false;
-    const proc = spawn(cmd[0], cmd.slice(1), { stdio: ["pipe", "ignore", "ignore"] });
+    const proc = spawn2(cmd[0], cmd.slice(1), { stdio: ["pipe", "ignore", "ignore"] });
     proc.stdin.write(text);
     proc.stdin.end();
     return new Promise((resolve) => {
@@ -1694,6 +2343,21 @@ async function copyToClipboard(text) {
 }
 
 // src/tips.ts
+var TipRotator = class {
+  tips;
+  lastIndex = -1;
+  constructor(tips) {
+    this.tips = tips ?? TIPS;
+  }
+  next() {
+    let idx;
+    do {
+      idx = Math.floor(Math.random() * this.tips.length);
+    } while (idx === this.lastIndex && this.tips.length > 1);
+    this.lastIndex = idx;
+    return this.tips[idx];
+  }
+};
 var TIPS = [
   "\u{1F4A1} Tip: Press ? to see all keyboard shortcuts",
   "\u{1F4A1} Tip: Use Ctrl+R to recall past searches",
@@ -1706,25 +2370,25 @@ var TIPS = [
   "\u{1F4A1} Tip: Press E to browse popular GitHub topics",
   "\u{1F4A1} Tip: Press Ctrl+P to copy a repo link to clipboard"
 ];
-var lastIndex = -1;
+var defaultRotator = new TipRotator();
 function nextTip() {
-  let idx;
-  do {
-    idx = Math.floor(Math.random() * TIPS.length);
-  } while (idx === lastIndex && TIPS.length > 1);
-  lastIndex = idx;
-  return TIPS[idx];
+  return defaultRotator.next();
 }
 
 // src/tui.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { join as join2, dirname } from "path";
-import { fileURLToPath } from "url";
+import { readFileSync as readFileSync5 } from "fs";
+import { join as join5, dirname as dirname4 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/update-check.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join4, dirname as dirname3 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 var REGISTRY_URL = "https://registry.npmjs.org/github-search-cli/latest";
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 var REQUEST_TIMEOUT_MS = 5e3;
+var __dirname2 = dirname3(fileURLToPath3(import.meta.url));
+var PKG_DIR2 = join4(__dirname2, "..");
 var STATE_FILE = "update-state.json";
 var DEFAULTS = {
   lastCheck: 0,
@@ -1819,10 +2483,38 @@ async function performUpdate() {
     return false;
   }
 }
+function recordPreUpdateState(currentVersion) {
+  writeUpdateState({
+    ...readUpdateState(),
+    lastInstalledVersion: currentVersion
+  });
+}
+function fetchReleaseNotes(version) {
+  try {
+    const notesPath = join4(PKG_DIR2, "release-notes", `${version}.md`);
+    const md = readFileSync4(notesPath, "utf-8");
+    if (md.trim().length > 0) return md;
+  } catch {
+  }
+  try {
+    const changelogPath = join4(PKG_DIR2, "CHANGELOG.md");
+    const changelog = readFileSync4(changelogPath, "utf-8");
+    const header = "## [" + version + "]";
+    const start = changelog.indexOf(header);
+    if (start === -1) return null;
+    const bodyStart = start + header.length;
+    const rest = changelog.substring(bodyStart);
+    const nextHeaderIdx = rest.indexOf("\n## ");
+    const end = nextHeaderIdx === -1 ? changelog.length : bodyStart + nextHeaderIdx;
+    return changelog.substring(bodyStart, end).trim();
+  } catch {
+  }
+  return null;
+}
 
 // src/tui.ts
-var __dirname = dirname(fileURLToPath(import.meta.url));
-var PKG_DIR = join2(__dirname, "..");
+var __dirname3 = dirname4(fileURLToPath4(import.meta.url));
+var PKG_DIR3 = join5(__dirname3, "..");
 var cachedVersion = null;
 var colors = {
   bg: "#3D3B3B",
@@ -3093,11 +3785,34 @@ async function launchBrowser(theme_override) {
     leaderSelect.focus();
     showOverlay("leader");
   }
+  function checkPostUpgradePanel() {
+    const state = readUpdateState();
+    if (state.suppressed) return;
+    if (!cachedVersion) {
+      try {
+        const pkg = JSON.parse(readFileSync5(join5(PKG_DIR3, "package.json"), "utf-8"));
+        cachedVersion = pkg.version;
+      } catch {
+        return;
+      }
+    }
+    const currentVersion2 = cachedVersion;
+    if (!state.lastInstalledVersion) return;
+    if (state.lastInstalledVersion === currentVersion2) return;
+    const notes = fetchReleaseNotes(currentVersion2);
+    const notesBlock = notes ? renderMarkdown(notes, { width: 60 }) : "  No release notes found for this version.";
+    updateSelectedOption = 0;
+    updateText.content = `  Updated ghfind ${state.lastInstalledVersion} \u2192 ${currentVersion2}
+
+${notesBlock}`;
+    renderUpdateOptions();
+    showOverlay("update");
+  }
   async function checkForUpdateAndShow(force = false) {
     if (!force && !shouldCheckUpdate()) return;
     if (cachedVersion === null) {
       try {
-        const pkg = JSON.parse(readFileSync2(join2(PKG_DIR, "package.json"), "utf-8"));
+        const pkg = JSON.parse(readFileSync5(join5(PKG_DIR3, "package.json"), "utf-8"));
         cachedVersion = pkg.version;
       } catch {
         debugLog("Failed to read package.json");
@@ -3109,12 +3824,19 @@ async function launchBrowser(theme_override) {
     markUpdateChecked(latest ?? void 0);
     if (latest) {
       updateSelectedOption = 0;
-      updateText.content = `  A new version is available
+      const notes = fetchReleaseNotes(latest);
+      const notesBlock = notes ? renderMarkdown(notes, { width: 60 }) : `  A new version is available
 
   Current: ${currentVersion2}
   Latest:   ${latest}
 
   Run "npm install -g ghfind"`;
+      updateText.content = `  A new version is available
+
+  Current: ${currentVersion2}
+  Latest:   ${latest}
+
+${notesBlock}`;
       renderUpdateOptions();
       showOverlay("update");
     } else {
@@ -3265,8 +3987,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";
@@ -3999,6 +4721,7 @@ ${pack.description ?? ""}`;
           const action = ["now", "later", "never"][updateSelectedOption];
           if (action === "now") {
             showOverlay("none");
+            recordPreUpdateState(cachedVersion ?? "");
             performUpdate().then((ok) => {
               if (ok) {
                 setStatus("\u2713 Update complete \u2014 restart ghfind");
@@ -4050,18 +4773,18 @@ ${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") {
@@ -4143,14 +4866,14 @@ ${pack.description ?? ""}`;
       return;
     }
   });
-  const pkgPath = join2(
-    dirname(fileURLToPath(import.meta.url)),
+  const pkgPath = join5(
+    dirname4(fileURLToPath4(import.meta.url)),
     "..",
     "package.json"
   );
   let currentVersion = "0.0.0";
   try {
-    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
     currentVersion = pkg.version;
   } catch {
   }
@@ -4158,6 +4881,7 @@ ${pack.description ?? ""}`;
     showLanding(true);
   }
   checkForUpdateAndShow();
+  checkPostUpgradePanel();
   renderer.start();
   if (session && session.mode) {
     if (currentMode === "trending") {
@@ -4202,8 +4926,8 @@ if (import.meta.main && false) {
 
 // src/cli.ts
 process.env.GHFIND_CLI_RUN = "1";
-var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
-var PKG_DIR2 = join3(__dirname2, "..");
+var __dirname4 = dirname5(fileURLToPath5(import.meta.url));
+var PKG_DIR4 = join6(__dirname4, "..");
 function parseArgs(args) {
   const flags = {
     query: "",
@@ -4217,13 +4941,15 @@ function parseArgs(args) {
     trending: false,
     since: "daily",
     watch: false,
+    releases: false,
     interval: 300,
     init: false,
     version: false,
     help: false,
     pkg: false,
     registry: "npm",
-    compare: []
+    compare: [],
+    doctor: false
   };
   let queryParts = [];
   for (let i = 0; i < args.length; i++) {
@@ -4247,10 +4973,17 @@ function parseArgs(args) {
       case "--watch":
         flags.watch = true;
         break;
+      case "--releases":
+        flags.releases = true;
+        break;
       case "--version":
       case "-v":
         flags.version = true;
         break;
+      case "--doctor":
+      case "doctor":
+        flags.doctor = true;
+        break;
       case "--help":
       case "-h":
         flags.help = true;
@@ -4314,10 +5047,16 @@ function parseArgs(args) {
 async function main() {
   const flags = parseArgs(process.argv.slice(2));
   if (flags.version) {
-    const pkg = JSON.parse(readFileSync3(join3(PKG_DIR2, "package.json"), "utf-8"));
+    const pkg = JSON.parse(
+      readFileSync6(join6(PKG_DIR4, "package.json"), "utf-8")
+    );
     console.log(`ghfind v${pkg.version}`);
     return;
   }
+  if (flags.doctor) {
+    await runDoctor();
+    return;
+  }
   if (flags.help) {
     console.log(`
 ghfind \u2014 Interactive GitHub repository browser
@@ -4331,6 +5070,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 --releases                Check bookmarks for new releases
   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
@@ -4338,6 +5078,7 @@ Usage:
   ghfind init                      Run setup wizard
   ghfind --completion <shell>      Print completion script (bash|zsh|fish)
   ghfind --version                 Print version
+  ghfind --doctor                  Run environment diagnostics (troubleshooting)
   ghfind --help                    Print this help
 
 Options:
@@ -4352,6 +5093,7 @@ Options:
   --registry <name>                  Registry for pkg: npm (default) | others TBD
 
   --watch                              Watch mode (re-run periodically)
+  --releases                           New-release feed for bookmarks
   --interval <s>                       Watch interval in seconds (default: 300)
   --completion <shell>                 Generate completions
 `);
@@ -4360,7 +5102,10 @@ Options:
   if (flags.completion) {
     const shell = flags.completion;
     try {
-      const content = readFileSync3(join3(PKG_DIR2, "completions", `ghfind.${shell}`), "utf-8");
+      const content = readFileSync6(
+        join6(PKG_DIR4, "completions", `ghfind.${shell}`),
+        "utf-8"
+      );
       console.log(content);
     } catch {
       console.error(`Completions not available for shell: ${shell}`);
@@ -4382,8 +5127,12 @@ Options:
     return;
   }
   const outputFormat = flags.json ? "json" : flags.csv ? "csv" : flags.markdown ? "markdown" : void 0;
-  const isNonInteractive = outputFormat || flags.count || flags.format || flags.pipe || flags.watch;
+  const isNonInteractive = outputFormat || flags.count || flags.format || flags.pipe || flags.watch || flags.releases;
   if (isNonInteractive) {
+    if (flags.releases) {
+      await runReleases(flags, outputFormat);
+      return;
+    }
     await runNonInteractive(flags, outputFormat);
     return;
   }
@@ -4402,20 +5151,32 @@ async function runPackageSearch(flags) {
     console.error(`Registry "${flags.registry}" not yet supported (only npm).`);
     process.exit(1);
   }
-  const PKG_SORTS = ["best-match", "score", "downloads", "name"];
+  const PKG_SORTS = [
+    "best-match",
+    "score",
+    "downloads",
+    "name"
+  ];
   const pkgSort = flags.sort;
   if (!PKG_SORTS.includes(pkgSort)) {
-    console.error(`Invalid sort for pkg: "${flags.sort}" (use best-match|score|downloads|name).`);
+    console.error(
+      `Invalid sort for pkg: "${flags.sort}" (use best-match|score|downloads|name).`
+    );
     process.exit(1);
   }
   const search = createPackageSearch();
   const query = flags.query.trim();
   if (!query) {
-    console.error("Usage: ghfind pkg <query> [--json|--csv|--markdown|--count|--format urls|names] [--limit <n>]");
+    console.error(
+      "Usage: ghfind pkg <query> [--json|--csv|--markdown|--count|--format urls|names] [--limit <n>]"
+    );
     process.exit(1);
   }
   try {
-    const { totalCount, packages } = await search.searchPackage(query, flags.limit);
+    const { totalCount, packages } = await search.searchPackage(
+      query,
+      flags.limit
+    );
     const sorted = sortPackages(packages, pkgSort);
     if (flags.count) {
       console.log(totalCount);
@@ -4431,7 +5192,9 @@ async function runPackageSearch(flags) {
       console.log(formatPackagesNames(sorted));
     } else {
       for (const p of sorted) {
-        console.log(`${p.name}@${p.version}  \u2193 ${p.downloads.toLocaleString()}  ${p.score.toFixed(2)}  ${p.description ?? ""}`);
+        console.log(
+          `${p.name}@${p.version}  \u2193 ${p.downloads.toLocaleString()}  ${p.score.toFixed(2)}  ${p.description ?? ""}`
+        );
       }
     }
   } catch (err) {
@@ -4439,6 +5202,28 @@ async function runPackageSearch(flags) {
     process.exit(1);
   }
 }
+async function runReleases(flags, outputFormat) {
+  const results2 = await checkAndNotify({ token: flags.token });
+  const releases = allCachedReleases();
+  if (outputFormat === "json") {
+    console.log(JSON.stringify(releases.map((r) => ({
+      fullName: r.fullName,
+      tag: r.tagName,
+      name: r.name,
+      url: r.url,
+      publishedAt: r.publishedAt,
+      prerelease: r.prerelease
+    })), null, 2));
+    return;
+  }
+  const unseen = results2.reduce((n, r) => n + r.newReleases.length, 0);
+  const errors = results2.filter((r) => r.error).length;
+  console.log(`Checked ${results2.length} bookmarked repos \u2014 ${unseen} new release${unseen === 1 ? "" : "s"}${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}.`);
+  for (const r of releases) {
+    console.log(`${r.fullName}  ${r.prerelease ? "[pre] " : ""}${r.tagName}  ${r.publishedAt.slice(0, 10)}
+  ${r.url}`);
+  }
+}
 async function runNonInteractive(flags, outputFormat) {
   const handlers = {
     trending: async (ctx2) => {
@@ -4446,7 +5231,13 @@ async function runNonInteractive(flags, outputFormat) {
       const trendingSearch = createTrendingSearch();
       const response = await trendingSearch.search(
         { keywords: [], qualifiers: [], raw: "trending" },
-        { limit: 25, sort: "stars", json: false, verbose: false, trendingSince: since }
+        {
+          limit: 25,
+          sort: "stars",
+          json: false,
+          verbose: false,
+          trendingSince: since
+        }
       );
       if (outputFormat) {
         console.log(format(response.repos, outputFormat));
@@ -4454,21 +5245,34 @@ async function runNonInteractive(flags, outputFormat) {
         console.log(response.totalCount);
       } else {
         for (const r of response.repos) {
-          console.log(r.fullName + "  \u2605 " + r.stars + "  \u25B2 +" + r.score + " " + since + "  \u25CF " + (r.language ?? ""));
+          console.log(
+            r.fullName + "  \u2605 " + r.stars + "  \u25B2 +" + r.score + " " + since + "  \u25CF " + (r.language ?? "")
+          );
         }
       }
     },
     watch: async (ctx2) => {
       let tick = 0;
       await runWatch(
-        { query: ctx2.query, sort: flags.sort, limit: flags.limit, token: flags.token, intervalMs: flags.interval * 1e3, trending: flags.trending },
+        {
+          query: ctx2.query,
+          sort: flags.sort,
+          limit: flags.limit,
+          token: flags.token,
+          intervalMs: flags.interval * 1e3,
+          trending: flags.trending
+        },
         (repos, delta) => {
           tick++;
           if (outputFormat) {
-            console.log(`[Watch #${tick}] ${repos.length} results (${delta >= 0 ? "+" : ""}${delta} since last check)`);
+            console.log(
+              `[Watch #${tick}] ${repos.length} results (${delta >= 0 ? "+" : ""}${delta} since last check)`
+            );
             console.log(format(repos, outputFormat));
           } else {
-            console.log(`[Watch #${tick}] ${repos.length} results \u2014 ${delta >= 0 ? "+" : ""}${delta} since last check`);
+            console.log(
+              `[Watch #${tick}] ${repos.length} results \u2014 ${delta >= 0 ? "+" : ""}${delta} since last check`
+            );
           }
         },
         (err) => console.error(`[Watch error] ${err.message}`)
@@ -4519,7 +5323,13 @@ async function runNonInteractive(flags, outputFormat) {
       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 }
+          {
+            limit: 1,
+            sort: "stars",
+            json: false,
+            verbose: false,
+            token: flags.token
+          }
         );
         repos.push(...res.repos);
       }
@@ -4531,7 +5341,11 @@ async function runNonInteractive(flags, outputFormat) {
   await handlers[key](ctx);
 }
 main().catch((err) => {
-  console.error("DEBUG: uncaught error:", err.message || err);
-  console.error(err instanceof Error ? err.message : String(err));
+  if (err instanceof Error && err.name === "SearchCliError") {
+    console.error(err.userMessage ?? err.message);
+  } else {
+    console.error(err instanceof Error ? err.message : String(err));
+    reportError(err);
+  }
   process.exit(1);
 });