github-search-cli 9.1.0 → 9.2.1

package/dist/cli.js

@@ -1,9 +1,8 @@
-#!/usr/bin/env node
 import {
   loadConfig,
   saveConfig,
   stateDir
-} from "./chunk-TUMYR2IC.js";
+} from "./chunk-IVUU2KGR.js";
 
 // src/errors.ts
 var SearchCliError = class extends Error {
@@ -491,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) {
@@ -513,8 +513,101 @@ function createTrendingSearch(logger2 = noopLogger) {
   return new SearchModule(new TrendingAdapter(logger2), logger2);
 }
 
-// src/output.ts
-import { writeFileSync } from "fs";
+// src/package.ts
+function normalizeNpmObject(obj) {
+  const p = obj.package;
+  const name = p.name ?? "";
+  return {
+    name,
+    version: p.version ?? "",
+    description: p.description ?? null,
+    url: p.links?.npm ?? `https://www.npmjs.com/package/${name}`,
+    downloads: obj.downloads?.monthly ?? 0,
+    score: obj.score?.final ?? obj.searchScore ?? 0,
+    publisher: p.publisher?.username ?? p.author?.name ?? null,
+    keywords: p.keywords ?? [],
+    registry: "npm"
+  };
+}
+function createPackageSearch() {
+  return {
+    async searchPackage(rawQuery, limit) {
+      const size = Math.min(Math.max(Math.trunc(limit) || 50, 1), 250);
+      const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(rawQuery)}&size=${size}`;
+      const res = await fetch(url, {
+        headers: { "User-Agent": "ghfind", Accept: "application/json" }
+      });
+      if (!res.ok) {
+        throw new Error(`npm search failed: HTTP ${res.status}`);
+      }
+      const data = await res.json();
+      const packages = (data.objects ?? []).map(normalizeNpmObject);
+      return { totalCount: data.total ?? packages.length, packages };
+    }
+  };
+}
+var PACKAGE_SORT_MODES = [
+  { key: "best-match", label: "best-match" },
+  { key: "downloads", label: "downloads" },
+  { key: "score", label: "score" },
+  { key: "name", label: "name" }
+];
+function sortPackages(pkgs, sort) {
+  if (sort === "best-match" || pkgs.length < 2) return pkgs;
+  const arr = [...pkgs];
+  if (sort === "score") {
+    arr.sort((a, b) => b.score - a.score);
+  } else if (sort === "downloads") {
+    arr.sort((a, b) => b.downloads - a.downloads);
+  } else {
+    arr.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  return arr;
+}
+function csvEscape(val) {
+  const str = String(val ?? "");
+  if (str.includes('"') || str.includes(",") || str.includes("\n")) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+function formatPackagesJson(pkgs) {
+  return JSON.stringify(pkgs, null, 2);
+}
+function formatPackagesCsv(pkgs) {
+  const header = "rank,name,version,downloads,score,url";
+  const rows = pkgs.map(
+    (p, i) => `${i + 1},${csvEscape(p.name)},${p.version},${p.downloads},${p.score.toFixed(2)},${csvEscape(p.url)}`
+  );
+  return [header, ...rows].join("\n");
+}
+function formatPackagesMarkdown(pkgs) {
+  const header = "| # | Package | Version | Downloads | Score |";
+  const sep = "|---|---------|---------|-----------|-------|";
+  const rows = pkgs.map(
+    (p, i) => `| ${i + 1} | [${p.name}@${p.version}](${p.url}) | ${p.version} | ${p.downloads.toLocaleString()} | ${p.score.toFixed(2)} |`
+  );
+  return [header, sep, ...rows].join("\n");
+}
+function formatPackagesUrls(pkgs) {
+  return pkgs.map((p) => p.url).join("\n");
+}
+function formatPackagesNames(pkgs) {
+  return pkgs.map((p) => p.name).join("\n");
+}
+
+// src/package-browser.ts
+import {
+  createCliRenderer,
+  BoxRenderable,
+  TextRenderable,
+  ScrollBoxRenderable,
+  StyledText,
+  bold,
+  fg,
+  dim,
+  t
+} from "@opentui/core";
 
 // src/open-url.ts
 function openUrl(url) {
@@ -527,7 +620,282 @@ function openUrl(url) {
   }
 }
 
+// src/package-browser.ts
+var C = {
+  bg: "#1a1b26",
+  surface: "#16161e",
+  text: "#a9b1d6",
+  muted: "#565f89",
+  cyan: "#7dcfff",
+  purple: "#bb9af7",
+  green: "#9ece6a",
+  gold: "#e0af68",
+  orange: "#ff9e64",
+  red: "#f7768e",
+  blue: "#7aa2f7",
+  lightBlue: "#b4f9f8",
+  selectionBg: "#3b6ce8",
+  selectionText: "#c0caf5",
+  border: "#363b54",
+  descText: "#6c7086",
+  // lighter muted for descriptions
+  nameText: "#c0caf5"
+  // bright for package names
+};
+var INT_FMT = new Intl.NumberFormat("en-US");
+function fmtCount(n) {
+  return INT_FMT.format(Math.trunc(n));
+}
+function formatPackageLine(pack) {
+  const nameStr = `${pack.name}@${pack.version}`.padEnd(28).slice(0, 28);
+  const dlStr = `\u2193 ${fmtCount(pack.downloads)}`.padEnd(20).slice(0, 20);
+  const scoreStr = `score ${pack.score.toFixed(2)}`.padEnd(12).slice(0, 12);
+  const desc = (pack.description ?? "").length > 60 ? (pack.description ?? "").slice(0, 57) + "..." : pack.description ?? "";
+  const line1 = t`${bold(fg(C.nameText)(nameStr))}${fg(C.cyan)(dlStr)}${fg(C.gold)(scoreStr)}`;
+  const line2 = t`${dim(fg(C.descText)(`     ${desc}`))}`;
+  const newline = { text: "\n", __isChunk: true };
+  const chunks = [...line1.chunks, newline, ...line2.chunks];
+  return new StyledText(chunks);
+}
+async function launchPackageBrowser() {
+  let renderer;
+  try {
+    renderer = await createCliRenderer();
+  } catch (err) {
+    console.error(
+      "Failed to start the interactive browser.\n",
+      `Reason: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    process.exit(1);
+    return;
+  }
+  const root = renderer.root;
+  root.flexDirection = "column";
+  let query = "";
+  let dirty = false;
+  let packages = [];
+  let selectedIdx = 0;
+  let isLoading = false;
+  const outerBox = new BoxRenderable(renderer, {
+    flexGrow: 1,
+    flexDirection: "column",
+    backgroundColor: C.bg,
+    border: true,
+    borderColor: C.border,
+    borderStyle: "rounded",
+    paddingX: 0,
+    paddingY: 0
+  });
+  const headerBox = new BoxRenderable(renderer, {
+    height: 1,
+    backgroundColor: C.bg,
+    paddingX: 1
+  });
+  const headerText = new TextRenderable(renderer, {
+    content: t`${bold(fg(C.purple)("\u27E0 tulipsearch"))}${fg(C.muted)(" \u2014 Packages")}`,
+    fg: C.purple,
+    bg: C.bg,
+    height: 1
+  });
+  headerBox.add(headerText);
+  outerBox.add(headerBox);
+  const inputBox = new BoxRenderable(renderer, {
+    height: 1,
+    flexDirection: "row",
+    backgroundColor: C.surface,
+    paddingX: 1
+  });
+  let inputText = null;
+  function renderInput() {
+    if (inputText) inputBox.remove(inputText);
+    const cursor = isLoading ? " " : "\u258A";
+    inputText = new TextRenderable(renderer, {
+      content: t`${fg(C.cyan)("\u276F ")}${query}${dim(fg(C.muted)(cursor))}`,
+      fg: C.text,
+      bg: C.surface,
+      height: 1
+    });
+    inputBox.add(inputText);
+  }
+  const statusBox = new BoxRenderable(renderer, {
+    height: 1,
+    backgroundColor: C.bg,
+    paddingX: 1
+  });
+  let statusText = null;
+  function setStatus(cfg) {
+    if (statusText) statusBox.remove(statusText);
+    statusText = new TextRenderable(renderer, {
+      content: cfg.content,
+      fg: cfg.color ?? C.text,
+      bg: C.bg,
+      height: 1
+    });
+    statusBox.add(statusText);
+  }
+  const scrollBox = new ScrollBoxRenderable(renderer, {
+    flexGrow: 1,
+    backgroundColor: C.bg,
+    scrollY: true,
+    scrollX: false,
+    viewportCulling: true
+  });
+  const rowBoxes = [];
+  const rowTexts = [];
+  function clearRows() {
+    for (const rb of rowBoxes) scrollBox.remove(rb);
+    rowBoxes.length = 0;
+    rowTexts.length = 0;
+  }
+  function rebuildList() {
+    clearRows();
+    packages.forEach((p, i) => {
+      const isEven = i % 2 === 0;
+      const isSelected = i === selectedIdx;
+      const rowBg = isSelected ? C.selectionBg : isEven ? C.bg : C.surface;
+      const rowText = new TextRenderable(renderer, {
+        content: formatPackageLine(p),
+        bg: rowBg,
+        height: 2
+      });
+      const rowBox = new BoxRenderable(renderer, {
+        flexDirection: "row",
+        backgroundColor: rowBg
+      });
+      rowBox.add(rowText);
+      rowBoxes.push(rowBox);
+      rowTexts.push(rowText);
+      scrollBox.add(rowBox);
+    });
+  }
+  const footerBox = new BoxRenderable(renderer, {
+    height: 1,
+    backgroundColor: C.bg,
+    paddingX: 1
+  });
+  const footerText = new TextRenderable(renderer, {
+    content: " type query \u21B5 search   \u2191\u2193 navigate   \u21B5 open   q/esc quit",
+    fg: C.muted,
+    bg: C.bg,
+    height: 1
+  });
+  footerBox.add(footerText);
+  outerBox.add(footerBox);
+  root.add(outerBox);
+  outerBox.add(inputBox);
+  outerBox.add(statusBox);
+  const divider = new TextRenderable(renderer, {
+    content: "\u2500".repeat(80),
+    fg: C.border,
+    bg: C.bg,
+    height: 1
+  });
+  outerBox.add(divider);
+  outerBox.add(scrollBox);
+  async function runSearch() {
+    const q = query.trim();
+    if (!q) return;
+    isLoading = true;
+    dirty = false;
+    clearRows();
+    setStatus({ content: t`${dim(fg(C.muted)(`  Loading packages for "${q}"...`))}` });
+    renderer.requestRender();
+    try {
+      const searcher = createPackageSearch();
+      const res = await searcher.searchPackage(q, 25);
+      packages = res.packages;
+      selectedIdx = 0;
+      rebuildList();
+      setStatus({
+        content: t`${fg(C.muted)(`  ${packages.length} of ${fmtCount(res.totalCount)} results for `)}${fg(C.cyan)(`"${q}"`)}`
+      });
+    } catch (err) {
+      packages = [];
+      clearRows();
+      const msg = err instanceof Error ? err.message : String(err);
+      setStatus({
+        content: t`${fg(C.red)(`  Error: ${msg.slice(0, 70)} \u2014 press \u21B5 to retry`)}`
+      });
+    }
+    isLoading = false;
+    renderInput();
+    renderer.requestRender();
+  }
+  function openSelectedPackage() {
+    if (selectedIdx < 0 || selectedIdx >= packages.length) return;
+    const p = packages[selectedIdx];
+    openUrl(p.url);
+  }
+  function moveSelection(delta) {
+    const oldIdx = selectedIdx;
+    const newIdx = Math.max(0, Math.min(packages.length - 1, oldIdx + delta));
+    if (newIdx === oldIdx) return;
+    selectedIdx = newIdx;
+    const setBg = (idx, selected) => {
+      if (idx < 0 || idx >= rowBoxes.length) return;
+      const bg = selected ? C.selectionBg : idx % 2 === 0 ? C.bg : C.surface;
+      rowBoxes[idx].backgroundColor = bg;
+      if (rowTexts[idx]) rowTexts[idx].bg = bg;
+    };
+    setBg(oldIdx, false);
+    setBg(newIdx, true);
+    renderer.requestRender();
+  }
+  renderer.keyInput.on("keypress", (key) => {
+    const name = key.name || "";
+    if (name === "q" || name === "escape") {
+      process.exit(0);
+      return;
+    }
+    if (name === "backspace") {
+      query = query.slice(0, -1);
+      dirty = true;
+      renderInput();
+      renderer.requestRender();
+      return;
+    }
+    if (name === "space") {
+      query += " ";
+      dirty = true;
+      renderInput();
+      renderer.requestRender();
+      return;
+    }
+    if (name.length === 1) {
+      query += name;
+      dirty = true;
+      renderInput();
+      renderer.requestRender();
+      return;
+    }
+    if (name === "up" || name === "k") {
+      moveSelection(-1);
+      return;
+    }
+    if (name === "down" || name === "j") {
+      moveSelection(1);
+      return;
+    }
+    if (name === "enter" || name === "return") {
+      if (dirty || packages.length === 0) {
+        runSearch();
+      } else {
+        openSelectedPackage();
+      }
+      return;
+    }
+  });
+  renderer.start();
+  renderInput();
+  setStatus({
+    content: t`${fg(C.muted)("  Type a package query above and press \u21B5 to search")}`
+  });
+  renderer.requestRender();
+}
+
 // src/output.ts
+import { writeFileSync } from "fs";
 var FORMATS = /* @__PURE__ */ new Map([
   // Export formats
   ["json", formatJson],
@@ -544,7 +912,7 @@ var FORMATS = /* @__PURE__ */ new Map([
 function formatJson(repos) {
   return JSON.stringify(repos, null, 2);
 }
-function csvEscape(val) {
+function csvEscape2(val) {
   const str = String(val ?? "");
   if (str.includes('"') || str.includes(",") || str.includes("\n")) {
     return `"${str.replace(/"/g, '""')}"`;
@@ -554,7 +922,7 @@ function csvEscape(val) {
 function formatCsv(repos) {
   const header = "rank,full_name,stars,forks,language,url";
   const rows = repos.map(
-    (r, i) => `${i + 1},${csvEscape(r.fullName)},${r.stars},${r.forks},${csvEscape(r.language ?? "")},${csvEscape(r.url)}`
+    (r, i) => `${i + 1},${csvEscape2(r.fullName)},${r.stars},${r.forks},${csvEscape2(r.language ?? "")},${csvEscape2(r.url)}`
   );
   return [header, ...rows].join("\n");
 }
@@ -664,36 +1032,42 @@ import { createInterface } from "readline";
 
 // src/themes.ts
 var THEMES = {
-  "premium-dark": {
-    name: "premium-dark",
-    bg: "#3D3B3B",
-    surface: "#4a4848",
-    surfaceAlt: "#525050",
-    text: "#e0e4f0",
-    muted: "#a8a6a6",
-    blue: "#89b4fa",
-    green: "#a6e3a1",
-    yellow: "#f9e2af",
-    red: "#f38ba8",
-    teal: "#94e2d5",
-    purple: "#cba6f7",
-    orange: "#fab387",
-    border: "#1C1C1C",
-    borderAlt: "#2a2a2a",
-    separator: "#1C1C1C",
-    selectionBg: "#2A2A9C",
-    selectionText: "#ffffff",
-    success: "#a6e3a1",
-    warning: "#f9e2af",
-    error: "#f38ba8"
-  },
   "tokyo-night": {
     name: "tokyo-night",
-    bg: "#3D3B3B",
-    surface: "#4a4848",
-    surfaceAlt: "#525050",
-    text: "#e0e4f0",
-    muted: "#a8a6a6",
+    // Genuine Tokyo Night palette — cool blue-violet mood
+    bg: "#1a1b26",
+    surface: "#24283b",
+    surfaceAlt: "#292e42",
+    text: "#c0caf5",
+    muted: "#565f89",
+    blue: "#7aa2f7",
+    green: "#9ece6a",
+    yellow: "#e0af68",
+    red: "#f7768e",
+    teal: "#73daca",
+    purple: "#bb9af7",
+    orange: "#ff9e64",
+    border: "#24283b",
+    borderAlt: "#1f2335",
+    separator: "#1f2335",
+    selectionBg: "#2d3f76",
+    selectionText: "#c0caf5",
+    success: "#9ece6a",
+    warning: "#e0af68",
+    error: "#f7768e",
+    surfaceDim: "#16161e",
+    accent: "#7aa2f7",
+    accentDim: "#5d7abf",
+    borderAccent: "#1f2335"
+  },
+  "premium-dark": {
+    name: "premium-dark",
+    // Warm counter-mood to Tokyo Night — amber/rust accent
+    bg: "#1e1e2e",
+    surface: "#262637",
+    surfaceAlt: "#2e2e42",
+    text: "#cdd6f4",
+    muted: "#6c7086",
     blue: "#89b4fa",
     green: "#a6e3a1",
     yellow: "#f9e2af",
@@ -701,60 +1075,18 @@ var THEMES = {
     teal: "#94e2d5",
     purple: "#cba6f7",
     orange: "#fab387",
-    border: "#1C1C1C",
-    borderAlt: "#2a2a2a",
-    separator: "#1C1C1C",
-    selectionBg: "#2A2A9C",
-    selectionText: "#ffffff",
+    border: "#313244",
+    borderAlt: "#2a2a3d",
+    separator: "#2a2a3d",
+    selectionBg: "#45475a",
+    selectionText: "#cdd6f4",
     success: "#a6e3a1",
     warning: "#f9e2af",
-    error: "#f38ba8"
-  },
-  dracula: {
-    name: "dracula",
-    bg: "#3D3B3B",
-    surface: "#4a4848",
-    surfaceAlt: "#525050",
-    text: "#f8f8f2",
-    muted: "#a8a6a6",
-    blue: "#8be9fd",
-    green: "#50fa7b",
-    yellow: "#f1fa8c",
-    red: "#ff5555",
-    teal: "#50fa7b",
-    purple: "#bd93f9",
-    orange: "#ffb86c",
-    border: "#1C1C1C",
-    borderAlt: "#2a2a2a",
-    separator: "#1C1C1C",
-    selectionBg: "#2A2A9C",
-    selectionText: "#ffffff",
-    success: "#50fa7b",
-    warning: "#f1fa8c",
-    error: "#ff5555"
-  },
-  monokai: {
-    name: "monokai",
-    bg: "#3D3B3B",
-    surface: "#4a4848",
-    surfaceAlt: "#525050",
-    text: "#f8f8f2",
-    muted: "#a8a6a6",
-    blue: "#66d9ef",
-    green: "#a6e22e",
-    yellow: "#e6db74",
-    red: "#f92672",
-    teal: "#a6e22e",
-    purple: "#ae81ff",
-    orange: "#fd971f",
-    border: "#1C1C1C",
-    borderAlt: "#2a2a2a",
-    separator: "#1C1C1C",
-    selectionBg: "#2A2A9C",
-    selectionText: "#f8f8f2",
-    success: "#a6e22e",
-    warning: "#e6db74",
-    error: "#f92672"
+    error: "#f38ba8",
+    surfaceDim: "#181825",
+    accent: "#f9e2af",
+    accentDim: "#c9a87a",
+    borderAccent: "#313244"
   }
 };
 function loadTheme(name) {
@@ -790,18 +1122,46 @@ async function runInitWizard() {
   const config = {
     defaultSort: ["best-match", "stars", "updated", "forks"].includes(sortStr) ? sortStr : "best-match",
     defaultLimit: Math.min(100, Math.max(10, parseInt(limitStr) || 50)),
-    theme: themes.includes(themeStr) ? themeStr : "tokyo-night",
+    theme: themes.includes(themeStr) ? themeStr : themes[0],
     cacheTtlSeconds: 300,
     defaultTab: "search"
   };
   if (token) config.githubToken = token;
   saveConfig(config);
-  const { configPath } = await import("./config-DFL44OVL.js");
+  const { configPath } = await import("./config-GNZOQRTH.js");
   console.log(`  \u2713 Config saved to ${configPath()}`);
   console.log("  Run 'ghfind' to start browsing!");
   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, 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");
+  }
+  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";
@@ -809,25 +1169,25 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/tui.ts
 import {
-  createCliRenderer as createCliRenderer2,
-  BoxRenderable as BoxRenderable2,
-  TextRenderable as TextRenderable2,
+  createCliRenderer as createCliRenderer3,
+  BoxRenderable as BoxRenderable3,
+  TextRenderable as TextRenderable3,
   InputRenderable,
   SelectRenderable,
-  ScrollBoxRenderable as ScrollBoxRenderable2
+  ScrollBoxRenderable as ScrollBoxRenderable3
 } from "@opentui/core";
 
 // src/trending.ts
 import {
-  createCliRenderer,
-  BoxRenderable,
-  TextRenderable,
-  ScrollBoxRenderable,
-  StyledText,
-  bold,
-  fg,
-  dim,
-  t
+  createCliRenderer as createCliRenderer2,
+  BoxRenderable as BoxRenderable2,
+  TextRenderable as TextRenderable2,
+  ScrollBoxRenderable as ScrollBoxRenderable2,
+  StyledText as StyledText2,
+  bold as bold2,
+  fg as fg2,
+  dim as dim2,
+  t as t2
 } from "@opentui/core";
 var TAB_NAMES = ["Today", "This Week", "This Month"];
 function tabSince(tab) {
@@ -853,6 +1213,16 @@ if (import.meta.main && false) {
 // src/help.ts
 function buildHelpSections() {
   return [
+    {
+      title: " Landing ",
+      titleColor: "blue",
+      rows: [
+        { keys: "\u2191 \u2193 / j k", action: "Navigate menu cards" },
+        { keys: "Enter", action: "Select mode" },
+        { keys: "? / h", action: "Toggle this help screen" },
+        { keys: "q", action: "Quit" }
+      ]
+    },
     {
       title: " Navigation ",
       titleColor: "blue",
@@ -882,6 +1252,17 @@ function buildHelpSections() {
         { keys: "\u2190 \u2192 / h l", action: "Navigate tabs" }
       ]
     },
+    {
+      title: " Packages Mode ",
+      titleColor: "cyan",
+      rows: [
+        { keys: "/", action: "Search npm packages" },
+        { keys: "\u2191 \u2193 / j k", action: "Move selection" },
+        { keys: "Enter", action: "View package details" },
+        { keys: "Space", action: "Open command menu" }
+      ],
+      note: "Search by name, description, or tags. Sort by downloads or score."
+    },
     {
       title: " Command Menu (Space)",
       titleColor: "purple",
@@ -894,9 +1275,17 @@ function buildHelpSections() {
         { keys: "Deep-dive", action: "Languages + contributors + excerpt" },
         { keys: "Bookmark", action: "Save / unsave selected repo" },
         { keys: "Compare", action: "Add to / remove from comparison" },
-        { keys: "Trending", action: "Switch to trending browser" }
+        { keys: "Trending", action: "Switch to trending browser" },
+        { keys: "Packages", action: "Switch to npm packages" },
+        { keys: "Export", action: "Export results to file" },
+        { keys: "Share", action: "Share repo as text" },
+        { keys: "Topics", action: "Browse GitHub topics" },
+        { keys: "Saved", action: "View saved searches" },
+        { keys: "Notifs", action: "Check GitHub notifications" },
+        { keys: "History", action: "View search history" },
+        { keys: "Help", action: "Show this help screen" }
       ],
-      note: "Also: Open, History, Export, Share, Topics, Saved, Notifs, Help"
+      note: "Navigate menu with \u2191 \u2193, select with Enter, back with \u2190 / Esc"
     },
     {
       title: " Overlay Keys ",
@@ -905,7 +1294,8 @@ function buildHelpSections() {
         { keys: "Esc / q", action: "Close any overlay" },
         { keys: "Enter", action: "Confirm selection / run action" },
         { keys: "d", action: "Delete entry (history, bookmarks, saved)" },
-        { keys: "\u2191 \u2193 / j k", action: "Navigate overlay list" }
+        { keys: "\u2191 \u2193 / j k", action: "Navigate overlay list" },
+        { keys: "\u2190 \u2192 / h l", action: "Navigate tabs / panels" }
       ]
     },
     {
@@ -915,23 +1305,26 @@ function buildHelpSections() {
         { keys: "keywords", action: "Free-text search" },
         { keys: "key:value", action: "Qualifier filter" },
         { keys: "-key:value", action: "Negated qualifier" },
-        { keys: '"phrase"', action: "Exact phrase match" }
+        { keys: '"phrase"', action: "Exact phrase match" },
+        { keys: "language:TypeScript", action: "Filter by language" },
+        { keys: "stars:>1000", action: "Minimum stars" },
+        { keys: "fork:true", action: "Include forks" },
+        { keys: "user:octocat", action: "User's repos" },
+        { keys: "org:facebook", action: "Organization repos" },
+        { keys: "repo:facebook/react", action: "Specific repo" },
+        { keys: "topic:react", action: "Filter by topic" },
+        { keys: "license:mit", action: "License type" },
+        { keys: "pushed:>2024-01-01", action: "Last push date" },
+        { keys: "archived:false", action: "Exclude archived" }
       ]
     },
     {
-      title: " Qualifiers ",
+      title: " Utility Keys ",
       titleColor: "muted",
       rows: [
-        { keys: "language:", action: "Filter by language" },
-        { keys: "stars:>N", action: "Minimum stars" },
-        { keys: "fork:true", action: "Include forks" },
-        { keys: "user:", action: "User's repos" },
-        { keys: "org:", action: "Organization repos" },
-        { keys: "repo:", action: "Specific repo" },
-        { keys: "topic:", action: "Filter by topic" },
-        { keys: "license:", action: "License type" },
-        { keys: "pushed:>YYYY-MM-DD", action: "Last push date" },
-        { keys: "archived:false", action: "Exclude archived" }
+        { keys: "t", action: "Cycle theme (light / dark / solarized)" },
+        { keys: "Ctrl+X", action: "Copy repo URL to clipboard" },
+        { keys: "Ctrl+C", action: "Copy search query to clipboard" }
       ]
     },
     {
@@ -1182,34 +1575,6 @@ 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");
-  }
-  lines.push("\u2514" + sep.map((s) => "\u2500" + s + "\u2500").join("\u2534") + "\u2518");
-  return lines.join("\n");
-}
-
 // src/explore.ts
 async function fetchTopics() {
   const res = await fetch("https://api.github.com/search/topics?q=popular&per_page=30", {
@@ -1465,7 +1830,6 @@ var colors = {
   surfaceAlt: "#525050",
   text: "#e0e4f0",
   muted: "#a8a6a6",
-  blue: "#89b4fa",
   green: "#a6e3a1",
   yellow: "#f9e2af",
   red: "#f38ba8",
@@ -1500,10 +1864,20 @@ var SORT_MODES = [
   { key: "updated", label: "updated" },
   { key: "forks", label: "forks" }
 ];
-async function launchBrowser() {
+async function launchBrowser(theme_override) {
   let renderer;
   try {
-    renderer = await createCliRenderer2();
+    const isTTY = process.stdout.isTTY && process.stdin.isTTY;
+    if (isTTY) {
+      renderer = await createCliRenderer3();
+    } else {
+      renderer = await createCliRenderer3({
+        width: 80,
+        height: 24,
+        screenMode: "main-screen",
+        autoFocus: false
+      });
+    }
   } catch (err) {
     const isNode = process.versions.bun === void 0;
     if (isNode) {
@@ -1526,10 +1900,16 @@ async function launchBrowser() {
   }
   const root = renderer.root;
   root.flexDirection = "column";
+  root.border = true;
+  root.borderTop = true;
+  root.borderBottom = true;
+  root.borderLeft = true;
+  root.borderRight = true;
+  root.borderColor = colors.borderAccent;
   root.backgroundColor = colors.bg;
   const config = loadConfig();
   const githubToken = config.githubToken || process.env.GITHUB_TOKEN;
-  const theme = loadTheme(config.theme);
+  const theme = loadTheme(theme_override || config.theme);
   Object.assign(colors, theme);
   const session = restoreSession();
   let currentRepos = [];
@@ -1538,6 +1918,9 @@ async function launchBrowser() {
   let currentQueryInput = session?.query ?? "";
   let isLoading = false;
   let currentMode = session?.mode ?? "search";
+  let packages = [];
+  let currentPackageSort = "best-match";
+  let packageResultsRaw = [];
   let trendingTab = session?.trendingTab ?? "This Week";
   let trendingPeriod = "this week";
   let graphFullscreen = false;
@@ -1548,7 +1931,7 @@ async function launchBrowser() {
   let deepDiveActive = false;
   let compareList = [];
   let quitArmed = false;
-  const header = new TextRenderable2(renderer, {
+  const header = new TextRenderable3(renderer, {
     content: " ghfind \u2014 GitHub repo browser   [/]search  [Space]menu  [\u2192]open  [?]help  [q]uit",
     backgroundColor: colors.bg,
     color: colors.muted,
@@ -1556,7 +1939,7 @@ async function launchBrowser() {
     borderBottom: true,
     borderBottomColor: colors.border
   });
-  const trendingTabBox = new BoxRenderable2(renderer, {
+  const trendingTabBox = new BoxRenderable3(renderer, {
     flexDirection: "row",
     height: 1,
     backgroundColor: colors.surface,
@@ -1566,12 +1949,12 @@ async function launchBrowser() {
   });
   const trendingTabTexts = [];
   function renderTrendingTabs() {
-    for (const t2 of trendingTabTexts) trendingTabBox.remove(t2);
+    for (const t3 of trendingTabTexts) trendingTabBox.remove(t3);
     trendingTabTexts.length = 0;
     TAB_NAMES.forEach((name, i) => {
       const isActive = name === trendingTab;
       const label = ` ${name} `;
-      const tt = new TextRenderable2(renderer, {
+      const tt = new TextRenderable3(renderer, {
         content: label,
         color: isActive ? colors.bg : colors.muted,
         backgroundColor: isActive ? colors.blue : colors.bg,
@@ -1580,7 +1963,7 @@ async function launchBrowser() {
       trendingTabTexts.push(tt);
       trendingTabBox.add(tt);
       if (i < TAB_NAMES.length - 1) {
-        const sp = new TextRenderable2(renderer, {
+        const sp = new TextRenderable3(renderer, {
           content: "  ",
           color: colors.muted,
           backgroundColor: colors.bg,
@@ -1593,16 +1976,20 @@ async function launchBrowser() {
   }
   root.add(header);
   root.add(trendingTabBox);
-  const searchBox = new BoxRenderable2(renderer, {
+  const gapBox = new BoxRenderable3(renderer, {
+    height: 1,
+    visible: true
+  });
+  root.add(gapBox);
+  const searchBox = new BoxRenderable3(renderer, {
     visible: true,
-    borderBottom: true,
-    borderBottomColor: colors.border,
-    title: " SEARCH ",
+    bordered: true,
+    borderColor: colors.border,
+    title: "",
     titleColor: colors.blue,
     width: "100%",
     flexDirection: "row",
-    paddingTop: 0,
-    paddingBottom: 0,
+    marginTop: 1,
     backgroundColor: colors.surface
   });
   const searchInput = new InputRenderable(renderer, {
@@ -1617,7 +2004,7 @@ async function launchBrowser() {
   });
   searchBox.add(searchInput);
   root.add(searchBox);
-  const toolbarText = new TextRenderable2(renderer, {
+  const toolbarText = new TextRenderable3(renderer, {
     content: formatToolbar(currentSort, currentLimit, totalCount),
     visible: true,
     // hidden in trending mode
@@ -1630,15 +2017,16 @@ async function launchBrowser() {
     paddingX: 1
   });
   root.add(toolbarText);
-  const body = new BoxRenderable2(renderer, {
+  const body = new BoxRenderable3(renderer, {
     flexDirection: "row",
     flexGrow: 1,
     gap: 1,
     paddingY: 1,
     paddingX: 1
   });
-  const resultsBox = new BoxRenderable2(renderer, {
-    borderBottom: true,
+  const resultsBox = new BoxRenderable3(renderer, {
+    bordered: true,
+    borderColor: colors.border,
     borderBottomColor: colors.border,
     title: " Results ",
     titleColor: colors.blue,
@@ -1666,8 +2054,9 @@ async function launchBrowser() {
     itemSpacing: 0
   });
   resultsBox.add(resultsSelect);
-  const detailBox = new BoxRenderable2(renderer, {
-    borderBottom: true,
+  const detailBox = new BoxRenderable3(renderer, {
+    bordered: true,
+    borderColor: colors.border,
     borderBottomColor: colors.border,
     title: " Details ",
     titleColor: colors.green,
@@ -1678,16 +2067,148 @@ async function launchBrowser() {
     focusable: false,
     backgroundColor: colors.surface
   });
-  const detailText = new TextRenderable2(renderer, {
+  const detailText = new TextRenderable3(renderer, {
     content: "",
-    color: colors.text
+    color: colors.text,
+    wrapMode: "none"
   });
   detailBox.add(detailText);
   body.add(resultsBox);
   body.add(detailBox);
   root.add(body);
+  const landingBox = new BoxRenderable3(renderer, {
+    visible: false,
+    flexGrow: 1,
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center"
+  });
+  root.add(landingBox);
+  const landingBanner = new TextRenderable3(renderer, {
+    content: [
+      " \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ",
+      "\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557",
+      "\u2588\u2588\u2551  \u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551",
+      "\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255D  \u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551",
+      "\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2551\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554",
+      " \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u255D     \u255A\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u255D"
+    ].join("\n"),
+    color: colors.accent,
+    backgroundColor: colors.bg,
+    height: 6
+  });
+  landingBox.add(landingBanner);
+  const landingOptions = [
+    {
+      icon: "\u{1F50D}",
+      title: "Repo Search",
+      desc: "Search GitHub repositories by query, language, stars, and more",
+      action: () => {
+        currentMode = "search";
+        showLanding(false);
+        showSearchMode();
+      }
+    },
+    {
+      icon: "\u{1F4E6}",
+      title: "Package Search",
+      desc: "Search npm packages by name, description, or tags",
+      action: () => {
+        currentMode = "packages";
+        showLanding(false);
+        showPackagesMode();
+      }
+    },
+    {
+      icon: "\u{1F525}",
+      title: "Trending",
+      desc: "Browse the hottest repos on GitHub right now",
+      action: () => {
+        currentMode = "trending";
+        showLanding(false);
+        loadTrending();
+      }
+    }
+  ];
+  let landingSelected = 0;
+  const landingCards = [];
+  for (let i = 0; i < landingOptions.length; i++) {
+    const opt = landingOptions[i];
+    const card = new BoxRenderable3(renderer, {
+      flexDirection: "column",
+      height: 5,
+      width: "60%",
+      marginTop: 1,
+      border: true,
+      borderColor: i === 0 ? colors.accent : colors.border,
+      paddingX: 1,
+      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,
+      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",
+    color: colors.muted,
+    backgroundColor: colors.bg,
+    height: 1,
+    marginTop: 1
+  });
+  landingBox.add(landingHint);
+  function showLanding(visible) {
+    landingBox.visible = visible;
+    if (visible) {
+      currentMode = "landing";
+      hideMainContent();
+      landingSelected = 0;
+      updateLandingCards();
+      renderer.requestRender();
+    }
+  }
+  function updateLandingCards() {
+    for (let i = 0; i < landingCards.length; i++) {
+      const isSel = i === landingSelected;
+      landingCards[i].borderColor = isSel ? colors.accent : colors.border;
+      const children = landingCards[i].children ?? [];
+      const titleChild = children[1];
+      if (titleChild) {
+        titleChild.color = isSel ? colors.accent : colors.text;
+      }
+    }
+  }
+  renderer.keyInput.on("keypress", (key) => {
+    if (currentMode === "landing") {
+      if (key.name === "up" || key.name === "k") {
+        landingSelected = Math.max(0, landingSelected - 1);
+        updateLandingCards();
+        renderer.requestRender();
+      } else if (key.name === "down" || key.name === "j") {
+        landingSelected = Math.min(landingOptions.length - 1, landingSelected + 1);
+        updateLandingCards();
+        renderer.requestRender();
+      } else if (key.name === "enter" || key.name === "return") {
+        landingOptions[landingSelected].action();
+      } else if (key.name === "?" || key.name === "h") {
+        showOverlay(currentOverlay === "help" ? "none" : "help");
+      } else if (key.name === "q") {
+        cleanup();
+      }
+      return;
+    }
+  });
   function hideMainContent() {
     trendingTabBox.visible = false;
+    gapBox.visible = false;
     searchBox.visible = false;
     toolbarText.visible = false;
     body.visible = false;
@@ -1697,6 +2218,7 @@ async function launchBrowser() {
       trendingTabBox.visible = true;
     } else {
       searchBox.visible = true;
+      gapBox.visible = true;
       toolbarText.visible = true;
     }
     body.visible = true;
@@ -1718,7 +2240,16 @@ async function launchBrowser() {
     updateDim.visible = false;
     if (type === "none") {
       currentOverlay = "none";
-      showMainContent();
+      if (currentMode === "landing") {
+        landingBox.visible = true;
+        body.visible = false;
+        trendingTabBox.visible = false;
+        gapBox.visible = false;
+        searchBox.visible = false;
+        toolbarText.visible = false;
+      } else {
+        showMainContent();
+      }
       renderer.requestRender();
       return;
     }
@@ -1757,14 +2288,14 @@ async function launchBrowser() {
     renderer.requestRender();
   }
   const helpSections = buildHelpSections();
-  const helpBox = new BoxRenderable2(renderer, {
+  const helpBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
     borderBottom: true,
     borderBottomColor: colors.border
   });
-  const helpScroll = new ScrollBoxRenderable2(renderer, {
+  const helpScroll = new ScrollBoxRenderable3(renderer, {
     flexGrow: 1,
     backgroundColor: colors.bg,
     scrollY: true,
@@ -1779,7 +2310,7 @@ async function launchBrowser() {
     }
   });
   for (const section of helpSections) {
-    const sectionBox = new BoxRenderable2(renderer, {
+    const sectionBox = new BoxRenderable3(renderer, {
       borderBottom: true,
       borderBottomColor: colors.border,
       title: section.title,
@@ -1793,7 +2324,7 @@ async function launchBrowser() {
     for (const row of section.rows) {
       const keys = row.keys.padEnd(HELP_KEYS_COLUMN);
       sectionBox.add(
-        new TextRenderable2(renderer, {
+        new TextRenderable3(renderer, {
           content: `  ${keys} ${row.action}`,
           color: colors.text
         })
@@ -1801,7 +2332,7 @@ async function launchBrowser() {
     }
     if (section.note) {
       sectionBox.add(
-        new TextRenderable2(renderer, {
+        new TextRenderable3(renderer, {
           content: `  ${section.note}`,
           color: colors.muted
         })
@@ -1811,7 +2342,7 @@ async function launchBrowser() {
   }
   helpBox.add(helpScroll);
   root.add(helpBox);
-  const historyBox = new BoxRenderable2(renderer, {
+  const historyBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -1848,7 +2379,7 @@ async function launchBrowser() {
     }
     historySelect.setSelectedIndex(0);
   }
-  const bookmarksBox = new BoxRenderable2(renderer, {
+  const bookmarksBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -1885,7 +2416,7 @@ async function launchBrowser() {
     }
     bookmarksSelect.setSelectedIndex(0);
   }
-  const savedBox = new BoxRenderable2(renderer, {
+  const savedBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -1907,7 +2438,7 @@ async function launchBrowser() {
   });
   savedBox.add(savedSelect);
   root.add(savedBox);
-  const topicsBox = new BoxRenderable2(renderer, {
+  const topicsBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -1932,10 +2463,10 @@ async function launchBrowser() {
   async function refreshTopics() {
     try {
       const topics = await fetchTopics();
-      topicsSelect.options = topics.map((t2) => ({
-        name: `${t2.name}  (${t2.repoCount.toLocaleString()} repos)`,
-        description: t2.description.slice(0, 80),
-        value: t2
+      topicsSelect.options = topics.map((t3) => ({
+        name: `${t3.name}  (${t3.repoCount.toLocaleString()} repos)`,
+        description: t3.description.slice(0, 80),
+        value: t3
       }));
     } catch {
       topicsSelect.options = [
@@ -1944,7 +2475,7 @@ async function launchBrowser() {
     }
     topicsSelect.setSelectedIndex(0);
   }
-  const exportBox = new BoxRenderable2(renderer, {
+  const exportBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -1983,7 +2514,7 @@ async function launchBrowser() {
   });
   exportBox.add(exportSelect);
   root.add(exportBox);
-  const compareBox = new BoxRenderable2(renderer, {
+  const compareBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -1992,14 +2523,14 @@ async function launchBrowser() {
     title: " Comparison ",
     titleColor: colors.yellow
   });
-  const compareText = new TextRenderable2(renderer, {
+  const compareText = new TextRenderable3(renderer, {
     content: "",
     color: colors.text,
     backgroundColor: colors.bg
   });
   compareBox.add(compareText);
   root.add(compareBox);
-  const notifsBox = new BoxRenderable2(renderer, {
+  const notifsBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -2008,7 +2539,7 @@ async function launchBrowser() {
     title: " Notifications ",
     titleColor: colors.yellow
   });
-  const notifsText = new TextRenderable2(renderer, {
+  const notifsText = new TextRenderable3(renderer, {
     content: "(no notifications)",
     color: colors.text,
     backgroundColor: colors.bg
@@ -2023,7 +2554,7 @@ async function launchBrowser() {
       notifsText.content = notifs2.map((n) => `  ${n.icon} ${n.message}`).join("\n");
     }
   }
-  const shareBox = new BoxRenderable2(renderer, {
+  const shareBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -2084,7 +2615,7 @@ async function launchBrowser() {
     }
     savedSelect.setSelectedIndex(0);
   }
-  const leaderDim = new BoxRenderable2(renderer, {
+  const leaderDim = new BoxRenderable3(renderer, {
     visible: false,
     position: "absolute",
     top: 0,
@@ -2095,7 +2626,7 @@ async function launchBrowser() {
     // 60% opacity black (hex alpha: 0x99 ≈ 153/255)
   });
   root.add(leaderDim);
-  const leaderBox = new BoxRenderable2(renderer, {
+  const leaderBox = new BoxRenderable3(renderer, {
     visible: false,
     position: "absolute",
     width: "80%",
@@ -2127,7 +2658,7 @@ async function launchBrowser() {
     selectedDescriptionColor: colors.selectionText,
     itemSpacing: 0
   });
-  const leaderFooter = new TextRenderable2(renderer, {
+  const leaderFooter = new TextRenderable3(renderer, {
     content: " \u2191\u2193 select   Enter run   Esc/q close ",
     color: colors.muted,
     backgroundColor: colors.surfaceDim,
@@ -2140,7 +2671,7 @@ async function launchBrowser() {
   leaderBox.add(leaderFooter);
   root.add(leaderDim);
   root.add(leaderBox);
-  const updateDim = new BoxRenderable2(renderer, {
+  const updateDim = new BoxRenderable3(renderer, {
     visible: false,
     position: "absolute",
     top: 0,
@@ -2150,7 +2681,7 @@ async function launchBrowser() {
     backgroundColor: "#00000088"
   });
   root.add(updateDim);
-  const updateBox = new BoxRenderable2(renderer, {
+  const updateBox = new BoxRenderable3(renderer, {
     visible: false,
     position: "absolute",
     width: "55%",
@@ -2169,20 +2700,20 @@ async function launchBrowser() {
     paddingLeft: 2,
     paddingRight: 2
   });
-  const updateText = new TextRenderable2(renderer, {
+  const updateText = new TextRenderable3(renderer, {
     content: "",
     color: colors.accent,
     backgroundColor: colors.surfaceDim
   });
   let updateSelectedOption = 0;
-  const updateOptionsRow = new BoxRenderable2(renderer, {
+  const updateOptionsRow = new BoxRenderable3(renderer, {
     flexDirection: "row",
     gap: 1,
     backgroundColor: colors.surfaceDim,
     height: 3,
     width: "100%"
   });
-  const updateNowBox = new BoxRenderable2(renderer, {
+  const updateNowBox = new BoxRenderable3(renderer, {
     border: true,
     borderColor: updateSelectedOption === 0 ? colors.yellow : colors.border,
     backgroundColor: colors.surfaceDim,
@@ -2191,13 +2722,13 @@ async function launchBrowser() {
     paddingLeft: 1,
     paddingRight: 1
   });
-  const updateNowText = new TextRenderable2(renderer, {
+  const updateNowText = new TextRenderable3(renderer, {
     content: "   Update Now  ",
     color: updateSelectedOption === 0 ? colors.yellow : colors.text,
     backgroundColor: colors.surfaceDim
   });
   updateNowBox.add(updateNowText);
-  const laterBox = new BoxRenderable2(renderer, {
+  const laterBox = new BoxRenderable3(renderer, {
     border: true,
     borderColor: updateSelectedOption === 1 ? colors.yellow : colors.border,
     backgroundColor: colors.surfaceDim,
@@ -2206,13 +2737,13 @@ async function launchBrowser() {
     paddingLeft: 1,
     paddingRight: 1
   });
-  const laterText = new TextRenderable2(renderer, {
+  const laterText = new TextRenderable3(renderer, {
     content: "  Later",
     color: updateSelectedOption === 1 ? colors.yellow : colors.text,
     backgroundColor: colors.surfaceDim
   });
   laterBox.add(laterText);
-  const neverBox = new BoxRenderable2(renderer, {
+  const neverBox = new BoxRenderable3(renderer, {
     border: true,
     borderColor: updateSelectedOption === 2 ? colors.yellow : colors.border,
     backgroundColor: colors.surfaceDim,
@@ -2221,7 +2752,7 @@ async function launchBrowser() {
     paddingLeft: 1,
     paddingRight: 1
   });
-  const neverText = new TextRenderable2(renderer, {
+  const neverText = new TextRenderable3(renderer, {
     content: "  Don't show again",
     color: updateSelectedOption === 2 ? colors.yellow : colors.text,
     backgroundColor: colors.surfaceDim
@@ -2238,7 +2769,7 @@ async function launchBrowser() {
   }
   updateOptionsRow.add(updateNowBox);
   updateOptionsRow.add(laterBox);
-  const updateFooter = new TextRenderable2(renderer, {
+  const updateFooter = new TextRenderable3(renderer, {
     content: "  \u2190\u2192 select  Enter  Esc/q close",
     color: colors.muted,
     backgroundColor: colors.surfaceDim,
@@ -2331,6 +2862,29 @@ async function launchBrowser() {
           }
         }
       );
+    } else if (currentMode === "packages") {
+      searchItems.push(
+        {
+          type: "action",
+          name: "Sort",
+          description: `Cycle package sort (current: ${currentPackageSort})`,
+          action: () => changePackageSort()
+        },
+        {
+          type: "action",
+          name: "Limit",
+          description: `Cycle result limit (current: ${currentLimit})`,
+          action: () => changeLimit()
+        },
+        {
+          type: "action",
+          name: "Refresh",
+          description: "Re-run current package search",
+          action: () => {
+            if (currentQueryInput) doPackageSearch(currentQueryInput);
+          }
+        }
+      );
     }
     if (searchItems.length > 0) {
       groups.push({
@@ -2407,6 +2961,15 @@ async function launchBrowser() {
       });
     }
     const navItems = [];
+    navItems.push({
+      type: "action",
+      name: "Packages",
+      description: "Search npm packages",
+      action: () => {
+        showOverlay("none");
+        showPackagesMode();
+      }
+    });
     if (currentMode === "search") {
       navItems.push({
         type: "action",
@@ -2634,7 +3197,7 @@ async function launchBrowser() {
       renderer.requestRender();
     }
   }
-  const readmeBox = new BoxRenderable2(renderer, {
+  const readmeBox = new BoxRenderable3(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.surface,
@@ -2643,7 +3206,7 @@ async function launchBrowser() {
     title: " README ",
     titleColor: colors.green
   });
-  const readmeScroll = new ScrollBoxRenderable2(renderer, {
+  const readmeScroll = new ScrollBoxRenderable3(renderer, {
     flexGrow: 1,
     backgroundColor: colors.bg,
     scrollY: true,
@@ -2657,14 +3220,14 @@ async function launchBrowser() {
       width: 1
     }
   });
-  const readmeText = new TextRenderable2(renderer, {
+  const readmeText = new TextRenderable3(renderer, {
     content: "",
     color: colors.text,
     backgroundColor: colors.bg
   });
   readmeScroll.add(readmeText);
   readmeBox.add(readmeScroll);
-  const readmeFooter = new TextRenderable2(renderer, {
+  const readmeFooter = new TextRenderable3(renderer, {
     content: "  \u2191\u2193/jk scroll  Esc/q close",
     color: colors.muted,
     backgroundColor: colors.bg,
@@ -2710,7 +3273,7 @@ async function launchBrowser() {
     }
     renderer.requestRender();
   }
-  const statusBar = new TextRenderable2(renderer, {
+  const statusBar = new TextRenderable3(renderer, {
     content: " Ready. Press Enter to search.",
     backgroundColor: colors.surface,
     color: colors.muted,
@@ -2735,7 +3298,8 @@ async function launchBrowser() {
     statusMgr.set("idle", msg);
   }
   function setToolbar() {
-    toolbarText.content = formatToolbar(currentSort, currentLimit, totalCount);
+    const sort = currentMode === "packages" ? currentPackageSort : currentSort;
+    toolbarText.content = formatToolbar(sort, currentLimit, totalCount);
     renderer.requestRender();
   }
   function updateDetail(repo) {
@@ -2845,33 +3409,38 @@ async function launchBrowser() {
     }
     const xAxis = `     \u2506${"\u2500".repeat(termW)}`;
     const weekLabels = `     \u2506 ${"1w".padEnd(Math.floor(termW / 4))} ${"13w".padEnd(Math.floor(termW / 4))} ${"26w".padEnd(Math.floor(termW / 4))} ${"52w"}`;
-    return [xAxis, weekLabels];
+    return [...lines, xAxis, weekLabels];
   }
   async function loadChart(repo) {
     detailText.content = "  Loading chart...";
     renderer.requestRender();
     try {
+      const headers = { "User-Agent": "ghfind/1.0" };
+      if (githubToken) headers.Authorization = `Bearer ${githubToken}`;
       const [chartRes, repoRes] = await Promise.all([
         fetch(
           `https://api.github.com/repos/${repo.owner}/${repo.name}/stats/participation`,
-          { headers: { "User-Agent": "ghfind/1.0" } }
+          { headers }
         ),
         fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}`, {
-          headers: { "User-Agent": "ghfind/1.0" }
-        }).then((r) => r.ok ? r.json() : null)
+          headers
+        }).then((r) => r.ok ? r.clone().json() : null)
       ]);
       let chartSection = "";
       if (chartRes.ok) {
         const data = await chartRes.json();
         if (data?.all && data.all.length >= 2) {
           chartCommitData = data.all;
-          const chartW = 60;
+          const termW = graphFullscreen ? (process.stdout.columns || 120) - 12 : Math.floor((process.stdout.columns || 120) / 2) - 12;
+          const chartW = Math.max(20, Math.min(60, termW));
           const chartH = 10;
           const chartLines = buildChartString(chartCommitData, chartW, chartH);
-          chartSection = ["", "Weekly commits (52 weeks)", ...chartLines].join(
-            "\n"
-          );
+          chartSection = ["", "Weekly commits (52 weeks)", ...chartLines].join("\n");
+        } else if (data?.message) {
+          chartSection = ["", `Chart unavailable: ${data.message}`].join("\n");
         }
+      } else {
+        chartSection = ["", `Chart unavailable (API ${chartRes.status})`].join("\n");
       }
       const desc = repo.description ?? "";
       const lang = repo.language ?? "\u2014";
@@ -2931,6 +3500,7 @@ async function launchBrowser() {
     searchBox.visible = false;
     toolbarText.visible = false;
     trendingTabBox.visible = true;
+    body.visible = true;
     renderTrendingTabs();
     resultsSelect.options = [
       { name: "  Loading trending...", description: "", value: null }
@@ -2982,12 +3552,69 @@ async function launchBrowser() {
   function showSearchMode() {
     currentMode = "search";
     trendingTabBox.visible = false;
+    gapBox.visible = false;
     searchBox.visible = true;
     toolbarText.visible = true;
+    body.visible = true;
     searchInput.placeholder = "Search GitHub repos (e.g. rust cli, or language:Rust stars:>100)";
     searchInput.focus();
     renderer.requestRender();
   }
+  function showPackagesMode() {
+    currentMode = "packages";
+    trendingTabBox.visible = false;
+    gapBox.visible = false;
+    searchBox.visible = true;
+    toolbarText.visible = true;
+    body.visible = true;
+    searchInput.placeholder = "Search npm packages (e.g. react, vue, typescript)";
+    searchInput.focus();
+    packages = [];
+    resultsSelect.options = [
+      { name: "", description: "Type a query and press Enter to search", value: null }
+    ];
+    detailText.content = "";
+    renderer.requestRender();
+  }
+  async function doPackageSearch(queryText) {
+    const q = queryText.trim();
+    if (q === "" || isLoading) return;
+    currentQueryInput = q;
+    isLoading = true;
+    resultsSelect.options = [
+      { name: "  Searching packages...", description: "", value: null }
+    ];
+    detailText.content = "";
+    statusMgr.set("searching", `Searching npm for "${q}"`);
+    renderer.requestRender();
+    try {
+      const search = createPackageSearch();
+      const result = await search.searchPackage(q, currentLimit);
+      totalCount = result.totalCount;
+      packageResultsRaw = result.packages;
+      packages = sortPackages(packageResultsRaw, currentPackageSort);
+      setToolbar();
+      if (packages.length > 0) {
+        resultsSelect.options = packages.map((p) => ({
+          name: `${p.name}@${p.version}`,
+          description: p.description ?? "",
+          value: p
+        }));
+        resultsSelect.setSelectedIndex(0);
+        statusMgr.set("success", `${packages.length} packages found`);
+      } else {
+        throw new NoResultsError(q);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      resultsSelect.options = [
+        { name: " (error)", description: "", value: null }
+      ];
+      statusMgr.set("error", msg.slice(0, 60));
+    }
+    isLoading = false;
+    renderer.requestRender();
+  }
   async function doSearch(queryText, append = false) {
     const q = queryText.trim();
     if (q === "" || isLoading) return;
@@ -3074,6 +3701,22 @@ async function launchBrowser() {
       renderer.requestRender();
     }
   }
+  function changePackageSort() {
+    const idx = PACKAGE_SORT_MODES.findIndex((m) => m.key === currentPackageSort);
+    const next = PACKAGE_SORT_MODES[(idx + 1) % PACKAGE_SORT_MODES.length];
+    currentPackageSort = next.key;
+    setToolbar();
+    if (packageResultsRaw.length > 0) {
+      packages = sortPackages(packageResultsRaw, currentPackageSort);
+      resultsSelect.options = packages.map((p) => ({
+        name: `${p.name}@${p.version}`,
+        description: p.description ?? "",
+        value: p
+      }));
+      resultsSelect.setSelectedIndex(0);
+      renderer.requestRender();
+    }
+  }
   function changeLimit() {
     const limits = [10, 25, 50, 100];
     const idx = limits.indexOf(currentLimit);
@@ -3084,22 +3727,40 @@ async function launchBrowser() {
   }
   searchInput.on("enter", () => {
     if (searchInput.value.trim() === "" || isLoading) return;
-    showSearchMode();
-    doSearch(searchInput.value);
+    if (currentMode === "packages") {
+      doPackageSearch(searchInput.value);
+    } else {
+      doSearch(searchInput.value);
+    }
   });
   resultsSelect.on("selectionChanged", () => {
     const opt = resultsSelect.getSelectedOption();
-    const repo = opt?.value;
-    if (repo) {
-      if (graphFullscreen) loadChart(repo);
-      else updateDetail(repo);
+    if (currentMode === "packages") {
+      const pack = opt?.value;
+      if (pack) {
+        detailText.content = `Package: ${pack.name}@${pack.version}
+Downloads: ${pack.downloads.toLocaleString()}
+Score: ${pack.score.toFixed(2)}
+${pack.description ?? ""}`;
+      }
+    } else {
+      const repo = opt?.value;
+      if (repo) {
+        if (graphFullscreen) loadChart(repo);
+        else updateDetail(repo);
+      }
     }
     renderer.requestRender();
   });
   resultsSelect.on("itemSelected", () => {
     const opt = resultsSelect.getSelectedOption();
-    const repo = opt?.value;
-    if (repo) openUrl(repo.url);
+    if (currentMode === "packages") {
+      const pack = opt?.value;
+      if (pack?.url) openUrl(pack.url);
+    } else {
+      const repo = opt?.value;
+      if (repo) openUrl(repo.url);
+    }
   });
   renderer.keyInput.on("keypress", (key) => {
     if (currentOverlay !== "none") {
@@ -3389,6 +4050,28 @@ async function launchBrowser() {
         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 === "c" && !searchInput.focused) {
+      if (currentOverlay === "compare") {
+        showOverlay("none");
+      } else {
+        toggleCompareOnSelected();
+        refreshCompare();
+        showOverlay("compare");
+      }
+      return;
     }
     if (key.name === "?" || key.name === "h" && key.ctrl) {
       showOverlay("help");
@@ -3471,18 +4154,23 @@ async function launchBrowser() {
     currentVersion = pkg.version;
   } catch {
   }
+  if (!session || !session.mode) {
+    showLanding(true);
+  }
   checkForUpdateAndShow();
   renderer.start();
-  if (currentMode === "trending") {
-    loadTrending();
-  } else {
-    searchInput.value = currentQueryInput;
-    if (currentQueryInput) {
-      doSearch(currentQueryInput);
+  if (session && session.mode) {
+    if (currentMode === "trending") {
+      loadTrending();
     } else {
-      showSearchMode();
+      searchInput.value = currentQueryInput;
+      if (currentQueryInput) {
+        doSearch(currentQueryInput);
+      } else {
+        showSearchMode();
+      }
+      searchInput.focus();
     }
-    searchInput.focus();
   }
   renderer.requestRender();
 }
@@ -3513,6 +4201,7 @@ 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, "..");
 function parseArgs(args) {
@@ -3531,7 +4220,10 @@ function parseArgs(args) {
     interval: 300,
     init: false,
     version: false,
-    help: false
+    help: false,
+    pkg: false,
+    registry: "npm",
+    compare: []
   };
   let queryParts = [];
   for (let i = 0; i < args.length; i++) {
@@ -3591,16 +4283,31 @@ function parseArgs(args) {
       case "--format":
         flags.format = args[++i];
         break;
-      case "--interval":
-        flags.interval = parseInt(args[++i]) || 300;
+      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": {
+        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);
     }
   }
+  if (queryParts[0] === "pkg") {
+    flags.pkg = true;
+    queryParts.shift();
+  }
   flags.query = queryParts.join(" ");
   return flags;
 }
@@ -3624,6 +4331,9 @@ 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)
   ghfind init                      Run setup wizard
   ghfind --completion <shell>      Print completion script (bash|zsh|fish)
@@ -3634,11 +4344,13 @@ Options:
   --json, --csv, --markdown, --count   Output format
   --limit <n>                          Max results (default: 50)
   --sort <strategy>                    Sort: best-match|stars|updated|forks
-  --token <token>                      GitHub API token
+  --theme <name>                     Theme: tokyo-night|premium-dark (default: tokyo-night)
   --trending                           Trending mode
   --since <period>                     Trending period: daily|weekly|monthly
   --pipe <target>                      Pipe target: clone|open
   --format <fmt>                       Line format: urls|names|ssh-urls|...
+  --registry <name>                  Registry for pkg: npm (default) | others TBD
+
   --watch                              Watch mode (re-run periodically)
   --interval <s>                       Watch interval in seconds (default: 300)
   --completion <shell>                 Generate completions
@@ -3660,13 +4372,22 @@ Options:
     await runInitWizard();
     return;
   }
+  if (flags.pkg) {
+    const interactive = !flags.query && !flags.json && !flags.csv && !flags.markdown && !flags.count && !flags.format;
+    if (interactive) {
+      await launchPackageBrowser();
+    } else {
+      await runPackageSearch(flags);
+    }
+    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;
   if (isNonInteractive) {
     await runNonInteractive(flags, outputFormat);
     return;
   }
-  await launchBrowser();
+  await launchBrowser(flags.theme);
 }
 function buildSearchContext(flags) {
   const parsed = applyFlagFilters(parseQuery(flags.query), {});
@@ -3676,6 +4397,48 @@ function buildSearchContext(flags) {
     provider: createGitHubSearch(void 0, flags.token ? [flags.token] : [])
   };
 }
+async function runPackageSearch(flags) {
+  if (flags.registry !== "npm") {
+    console.error(`Registry "${flags.registry}" not yet supported (only npm).`);
+    process.exit(1);
+  }
+  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).`);
+    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>]");
+    process.exit(1);
+  }
+  try {
+    const { totalCount, packages } = await search.searchPackage(query, flags.limit);
+    const sorted = sortPackages(packages, pkgSort);
+    if (flags.count) {
+      console.log(totalCount);
+    } else if (flags.json) {
+      console.log(formatPackagesJson(sorted));
+    } else if (flags.csv) {
+      console.log(formatPackagesCsv(sorted));
+    } else if (flags.markdown) {
+      console.log(formatPackagesMarkdown(sorted));
+    } else if (flags.format === "urls") {
+      console.log(formatPackagesUrls(sorted));
+    } else if (flags.format === "names") {
+      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 ?? ""}`);
+      }
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
 async function runNonInteractive(flags, outputFormat) {
   const handlers = {
     trending: async (ctx2) => {
@@ -3749,13 +4512,26 @@ 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);
 }
 main().catch((err) => {
+  console.error("DEBUG: uncaught error:", err.message || err);
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);
 });