github-search-cli 9.3.0 → 9.4.0

package/src/doctor.ts

@@ -0,0 +1,287 @@
+/**
+ * `ghfind --doctor` — environment diagnostics for troubleshooting
+ * installation / launch problems (missing Bun, wrong libc build, bad config).
+ *
+ * Runs a battery of checks and prints a PASS / WARN / FAIL report, then exits
+ * non-zero if any FAIL check was detected.
+ */
+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";
+import { loadConfig, configPath, stateDir, cacheDir } from "./config";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = join(__dirname, "..");
+
+type CheckStatus = "PASS" | "WARN" | "FAIL";
+interface CheckResult {
+  status: CheckStatus;
+  label: string;
+  detail: string;
+}
+
+const results: CheckResult[] = [];
+
+function add(status: CheckStatus, label: string, detail: string): void {
+  results.push({ status, label, detail });
+}
+
+function run(
+  cmd: string,
+  args: string[],
+): { status: number | null; stdout: string; stderr: string } {
+  try {
+    const res = spawnSync(cmd, args, { encoding: "utf8", timeout: 15000 });
+    return {
+      status: res.status,
+      stdout: res.stdout ?? "",
+      stderr: res.stderr ?? "",
+    };
+  } catch {
+    return { status: null, stdout: "", stderr: "" };
+  }
+}
+
+function hasSystemBun(): { ok: boolean; version?: string } {
+  const res = run("bun", ["--version"]);
+  return res.status === 0
+    ? { ok: true, version: res.stdout.trim() }
+    : { ok: false };
+}
+
+function bundledBunPath(): string {
+  return join(PKG_DIR, "vendor", platform() === "win32" ? "bun.exe" : "bun");
+}
+
+/** Verify a bun binary actually runs (wrong libc flavor → ENOENT / segfault). */
+function bunRuns(bin: string): { ok: boolean; version?: string } {
+  const res = run(bin, ["--version"]);
+  if (res.status !== 0) return { ok: false };
+  return { ok: true, version: res.stdout.trim() };
+}
+
+function detectLibc(): "musl" | "glibc" | "unknown" {
+  if (platform() !== "linux") return "unknown";
+  try {
+    const osRelease = readFileSync("/etc/os-release", "utf8");
+    if (/alpine|musl/i.test(osRelease)) return "musl";
+  } catch {
+    // ignore
+  }
+  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(): Promise<void> {
+  const runningOnBun = process.versions.bun !== undefined;
+  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(): { ok: boolean } {
+  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: boolean): void {
+  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(): void {
+  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(): void {
+  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(): void {
+  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(): void {
+  const isTTY = process.stdout.isTTY && process.stdin.isTTY;
+  add(
+    isTTY ? "PASS" : "WARN",
+    "Terminal (TTY)",
+    isTTY
+      ? "stdin/stdout are TTYs — TUI can render."
+      : "stdin/stdout are not TTYs — the TUI cannot render (piped/non-interactive).",
+  );
+}
+
+function checkConfig(): void {
+  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(): void {
+  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}…).`);
+  } else {
+    add(
+      "WARN",
+      "GitHub token",
+      "No token found. Unauthenticated requests hit lower rate limits.",
+    );
+  }
+}
+
+function checkDirs(): void {
+  for (const [label, dir] of [
+    ["State dir", stateDir()],
+    ["Cache dir", cacheDir()],
+  ] as const) {
+    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(): void {
+  const colors = (s: string, n: CheckStatus) => {
+    const code =
+      n === "PASS" ? "\x1b[32m" : n === "WARN" ? "\x1b[33m" : "\x1b[31m";
+    return `${code}${s}\x1b[0m`;
+  };
+
+  console.log("\n  ghfind doctor — environment diagnostics");
+  console.log(`  ${platform()} ${arch} · ${homedir()}`);
+  console.log("  ─────────────────────────────────────────");
+  for (const r of results) {
+    console.log(
+      `  ${colors(r.status.padEnd(4), r.status)}  ${r.label}: ${r.detail}`,
+    );
+  }
+  console.log("  ─────────────────────────────────────────");
+
+  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) — ghfind should work, but review the items above.`,
+    );
+  } else {
+    console.log(
+      `  ${fails} failed check(s). Resolve these before running the TUI.`,
+    );
+  }
+  console.log("");
+}
+
+export async function runDoctor(): Promise<void> {
+  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;
+}

package/src/error-report.ts

@@ -0,0 +1,157 @@
+/**
+ * Error report helper — build a GitHub-issue pre-fill URL from an uncaught
+ * error, print it, and offer to open it in the user's browser.
+ *
+ * Privacy: never auto-posts. The user sees the URL and decides whether to
+ * submit. We redact env vars and only include what the diagnostic needs.
+ */
+import { platform as osPlatform, arch as osArch, version as nodeVersion, versions as nodeVersions } from "process";
+import { spawn } from "child_process";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// ponytail: in bun, process.platform is a string property; in node, same.
+// We need it as a string, not a function call.
+const _osPlatform = osPlatform;
+const _osArch = osArch;
+void _osPlatform;
+void _osArch;
+
+const REPO = "codersdfs/search-cli";
+const NEW_ISSUE_URL = `https://github.com/${REPO}/issues/new`;
+
+function getPackageVersion(): string {
+  try {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(__dirname, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function runtimeName(): string {
+  // ponytail: process.versions.bun is the cheapest probe and works in both runtimes
+  const bunVer = (nodeVersions as Record<string, string | undefined>).bun;
+  return bunVer ? `Bun ${bunVer}` : `Node ${nodeVersion}`;
+}
+
+/**
+ * Format an error into a GitHub issue body. Strips ANSI from stack traces,
+ * truncates long messages, redacts common secret patterns.
+ */
+export function formatErrorBody(
+  err: unknown,
+  context: { command: string; argv: string[] },
+): string {
+  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");
+}
+
+/**
+ * Build a pre-filled GitHub "new issue" URL from an error.
+ */
+export function buildIssueUrl(
+  err: unknown,
+  context: { command: string; argv: string[] },
+): string {
+  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()}`;
+}
+
+/**
+ * Try to open a URL in the user's default browser. Platform-aware, with a
+ * Node fallback so this works even when `Bun.spawn` isn't available.
+ */
+function tryOpenUrl(url: string): boolean {
+  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;
+    }
+    // Node fallback — use child_process.spawn detached so it survives exit
+    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;
+  }
+}
+
+/**
+ * Print the report URL and optionally try to open it. Always returns the URL
+ * so the caller can log it regardless of whether the browser opened.
+ */
+export function reportError(
+  err: unknown,
+  context: { command: string; argv: string[] } = {
+    command: "ghfind",
+    argv: process.argv.slice(2),
+  },
+): string {
+  const url = buildIssueUrl(err, context);
+  console.error("");
+  console.error("  ⚠  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("  → Opened: " + url);
+  } else {
+    console.error("  Copy this URL to file a bug report:");
+    console.error("");
+    console.error("    " + url);
+  }
+  console.error("");
+  return url;
+}

package/src/help.ts

@@ -17,7 +17,8 @@ export function buildHelpSections(): HelpSection[] {
       titleColor: "blue",
       rows: [
         { keys: "↑ ↓ / 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" },
       ],
@@ -39,6 +40,9 @@ export function buildHelpSections(): HelpSection[] {
       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" },
       ],
@@ -86,13 +90,24 @@ export function buildHelpSections(): HelpSection[] {
       ],
       note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc",
     },
+    {
+      title: " Bookmarks Page ",
+      titleColor: "green",
+      rows: [
+        { keys: "↑ ↓ / j k", action: "Move selection" },
+        { keys: "Enter", action: "Open bookmark in browser" },
+        { keys: "d", action: "Remove bookmark" },
+        { keys: "Esc / ←", action: "Back to landing" },
+      ],
+      note: "A full page, not an overlay — 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: "↑ ↓ / j k", action: "Navigate overlay list" },
         { keys: "← → / h l", action: "Navigate tabs / panels" },
       ],

package/src/landing.ts

@@ -0,0 +1,104 @@
+/** Landing screen pieces that are worth testing in isolation. */
+import { BoxRenderable, TextRenderable } from "@opentui/core";
+
+export interface LandingButtonColors {
+  accent: string;
+  border: string;
+  text: string;
+}
+
+/** Label for the landing-screen bookmarks button. */
+export function bookmarksButtonLabel(count: number): string {
+  if (count <= 0) return "\u{1F516}  Bookmarks  (none yet)";
+  if (count === 1) return "\u{1F516}  Bookmarks  (1 saved)";
+  return `\u{1F516}  Bookmarks  (${count} saved)`;
+}
+
+/**
+ * Whether the landing screen should consume navigation keys.
+ * False once another mode owns the screen (search, trending, packages,
+ * or the bookmarks page) or an overlay (help, ...) is open on top.
+ */
+export function landingKeysActive(mode: string, overlay: string): boolean {
+  return mode === "landing" && overlay === "none";
+}
+
+/** Keys the landing screen consumes; anything else falls through. */
+const LANDING_KEYS = new Set([
+  "up",
+  "k",
+  "down",
+  "j",
+  "enter",
+  "return",
+  "b",
+  "?",
+  "h",
+  "q",
+]);
+
+/**
+ * Whether the landing screen consumes this key. Callers must stop propagation
+ * for these, or the *same* event reaches the global handler next — e.g.
+ * Enter opening the bookmarks page and then immediately being re-read as
+ * "open the selected bookmark in a browser".
+ */
+export function landingConsumesKey(name: string): boolean {
+  return LANDING_KEYS.has(name);
+}
+
+/** Clamped selection movement for the landing menu (no wrap-around). */
+export function moveSelection(
+  current: number,
+  delta: number,
+  total: number,
+): number {
+  if (total <= 0) return 0;
+  return Math.min(total - 1, Math.max(0, current + delta));
+}
+
+/**
+ * Compact bordered button rendered under the landing mode cards.
+ * Highlights like a card when selected; label carries the bookmark count.
+ */
+export function createBookmarksButton(
+  renderer: ConstructorParameters<typeof BoxRenderable>[0],
+  colors: LandingButtonColors,
+) {
+  const box = new BoxRenderable(renderer, {
+    height: 3,
+    width: "60%",
+    marginTop: 1,
+    border: true,
+    borderColor: colors.border,
+    paddingX: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    focusable: false,
+  });
+  const label = new TextRenderable(renderer, {
+    content: bookmarksButtonLabel(0),
+    color: colors.text,
+    height: 1,
+  });
+  box.add(label);
+
+  return {
+    box,
+    setCount(n: number): void {
+      label.content = bookmarksButtonLabel(n);
+    },
+    setSelected(selected: boolean): void {
+      box.borderColor = selected ? colors.accent : colors.border;
+      label.color = selected ? colors.accent : colors.text;
+    },
+    get labelText(): string {
+      return label.content as string;
+    },
+    get borderColor(): unknown {
+      return box.borderColor;
+    },
+  };
+}
+
+export type BookmarksButton = ReturnType<typeof createBookmarksButton>;

package/src/notifications.ts

@@ -3,7 +3,7 @@ import { readJSON, writeJSON } from "./storage";
 
 export interface Notification {
   id: number;
-  type: "info" | "warning" | "rate-limit" | "watch-change" | "upgrade";
+  type: "info" | "warning" | "rate-limit" | "watch-change" | "upgrade" | "release";
   icon: string;
   message: string;
   timestamp: number;
@@ -39,6 +39,7 @@ function iconFor(type: Notification["type"]): string {
     case "rate-limit": return "🚫";
     case "watch-change": return "🔔";
     case "upgrade": return "📦";
+    case "release": return "🚀";
   }
 }