github-search-cli 0.8.2 → 0.9.0

package/README.md

@@ -25,11 +25,11 @@ npm install -g github-search-cli
 > **No separate runtime needed!** The package bundles a Bun binary, so the TUI
 > works out of the box on Windows, macOS, and Linux — no Node FFI, no `--experimental-ffi`.
 >
-> | Runtime | TUI | CLI modes |
-> |---------|-----|-----------|
-> | Bundled Bun | ✅ | ✅ |
-> | System Bun | ✅ | ✅ |
-> | Node 20+ | ✅ | ✅ |
+> | Runtime     | TUI | CLI modes |
+> | ----------- | --- | --------- |
+> | Bundled Bun | ✅  | ✅        |
+> | System Bun  | ✅  | ✅        |
+> | Node 20+    | ✅  | ✅        |
 
 ## Use
 
@@ -67,61 +67,87 @@ ghfind --completion fish | source
 
 ---
 
-## Changelog
-
-### v0.8.1
-- Fixed postinstall to download Bun binary correctly on all platforms
-- Fixed zip asset names to match Bun's current release naming
-- Fixed zip parsing to use central directory instead of local file headers
-- Removed `vendor/` from npm package (Bun binary downloaded at install time)
-- Changed `postinstall` to use `node` instead of `bun run` (works without Bun pre-installed)
-- TUI now works on Node.js 20+ via bundled Bun binary
-
----
-
 ## Features
 
 <table>
 <tr><td><b>Search</b></td><td>Free-text + qualifiers (<code>language:</code>, <code>stars:</code>, <code>topic:</code>), sort by stars/updated/forks</td></tr>
 <tr><td><b>Trending</b></td><td>Today, week, month, year — filter by language</td></tr>
-<tr><td><b>Bookmarks</b></td><td><code>b</code> / <code>B</code> — save repos, tag them</td></tr>
-<tr><td><b>Deep-dive</b></td><td><code>d</code> — languages, contributors, README, activity chart</td></tr>
-<tr><td><b>Compare</b></td><td><code>c</code> / <code>C</code> — side-by-side, select 2+ repos</td></tr>
-<tr><td><b>Explore</b></td><td><code>E</code> — browse popular topics</td></tr>
-<tr><td><b>History</b></td><td><code>Ctrl+R</code> — recall past searches</td></tr>
-<tr><td><b>Export</b></td><td><code>Ctrl+E</code> — JSON, CSV, Markdown to file</td></tr>
-<tr><td><b>Share</b></td><td><code>Ctrl+P</code> — copy to clipboard (markdown, plain, gh-cli)</td></tr>
+<tr><td><b>Bookmarks</b></td><td>Space → Bookmark / Bookmarks panel — save repos, tag them</td></tr>
+<tr><td><b>Deep-dive</b></td><td>Space → Deep-dive — languages, contributors, README, activity chart</td></tr>
+<tr><td><b>Compare</b></td><td>Space → Compare select / Compare view — side-by-side, select 2+ repos</td></tr>
+<tr><td><b>Explore</b></td><td>Space → Topics — browse popular GitHub topics</td></tr>
+<tr><td><b>History</b></td><td>Space → History — recall past searches</td></tr>
+<tr><td><b>Saved</b></td><td>Space → Saved searches — load or save queries</td></tr>
+<tr><td><b>Export</b></td><td>Space → Export — JSON, CSV, Markdown to file</td></tr>
+<tr><td><b>Share</b></td><td>Space → Share repo — copy repo link to clipboard</td></tr>
+<tr><td><b>Notifications</b></td><td>Space → Notifications — view & dismiss alerts</td></tr>
+<tr><td><b>Graph</b></td><td>Space → Activity graph — commit chart, fullscreen toggle</td></tr>
+<tr><td><b>Help</b></td><td><code>?</code> / <code>Ctrl+H</code> — keybindings reference</td></tr>
 <tr><td><b>Watch</b></td><td><code>--watch</code> — poll for new results</td></tr>
 </table>
 
 <details>
 <summary>Keybindings</summary>
 
-| Key | Action |
-|-----|--------|
-| `/` | Focus search |
-| `Enter` | Search / open repo |
-| `↑`/`↓` / `j`/`k` | Navigate |
-| `t` | Toggle search / trending |
-| `s` | Cycle sort |
-| `l` | Cycle limit |
-| `r` | Refresh |
-| `d` | Deep-dive |
-| `o` | Open in browser |
-| `b` / `B` | Bookmark / bookmarks panel |
-| `c` / `C` | Compare select / view |
-| `E` | Topic explorer |
-| `Tab` | Auto-complete qualifier |
-| `?` / `Ctrl+H` | Help |
-| `Ctrl+R` | History |
-| `Ctrl+S` / `Ctrl+O` | Save / open searches |
-| `Ctrl+E` | Export |
-| `Ctrl+N` | Notifications |
-| `Ctrl+P` | Share |
-| `Esc` | Close overlay |
-| `q` | Quit |
-
-Trending tabs: `1`–`5` (Today → All) or `←`/`→` / `h`/`l`
+**Global shortcuts** (main view, no overlay active)
+
+| Key                   | Action                                         |
+| --------------------- | ---------------------------------------------- |
+| `/`                   | Focus search input                             |
+| `Enter`               | Execute search / open selected repo in browser |
+| `↑` / `↓` — `j` / `k` | Navigate results & menus                       |
+| `Space`               | Open leader menu (contextual actions)          |
+| `Tab`                 | Auto-complete search qualifier                 |
+| `?` or `Ctrl+H`       | Help overlay                                   |
+| `1`–`5`               | Switch trending tabs (Today → All)             |
+| `←` / `→` — `h` / `l` | Switch trending tabs (left/right)              |
+| `PageUp`              | Jump to top of results                         |
+| `PageDown`            | Load next page of results                      |
+| `Esc`                 | Close current overlay                          |
+| `q`                   | Quit ghfind                                    |
+
+**Leader menu** — press `Space`, navigate with `↑`/`↓`, press `Enter` to dispatch
+
+Actions shown depend on current mode (search vs trending) and selection:
+
+| Menu item       | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| Sort            | Cycle sort strategy (best-match, stars, updated, forks) |
+| Limit           | Cycle result limit (10, 25, 50, 100)                    |
+| Refresh         | Re-run current search (or reload trending)              |
+| Toggle trending | Switch between search and trending views                |
+| Deep-dive       | Show languages, contributors, README excerpt            |
+| Readme          | Full README viewer                                      |
+| Activity graph  | Toggle commit chart fullscreen                          |
+| Bookmark        | Save / unsave selected repo                             |
+| Compare         | Add/remove repo to comparison set                       |
+| Compare view    | Show side-by-side comparison table                      |
+| Open in browser | Open selected repo URL                                  |
+| History         | Recall past searches                                    |
+| Saved searches  | Load a saved search                                     |
+| Save search     | Save current query                                      |
+| Export          | Export results to JSON / CSV / Markdown                 |
+| Share repo      | Copy repo link to clipboard                             |
+| Notifications   | View and dismiss alerts                                 |
+| Topics          | Browse popular GitHub topics                            |
+| Bookmarks panel | Browse saved bookmarks                                  |
+| Help            | Keybindings reference                                   |
+
+**Overlay-specific shortcuts**
+
+| Key             | Context                                              | Action                                      |
+| --------------- | ---------------------------------------------------- | ------------------------------------------- |
+| `Esc` / `q`     | Any overlay                                          | Close overlay                               |
+| `Enter`         | Leader / History / Saved / Export / Topics / Share   | Confirm selection                           |
+| `d`             | History / Bookmarks / Saved searches / Notifications | Delete current entry                        |
+| `Ctrl+X`        | History                                              | Clear all history                           |
+| `Ctrl+C`        | Notifications                                        | Dismiss all notifications                   |
+| `Y` / `N` / `L` | Update modal                                         | Yes (install) / No (skip) / Later (dismiss) |
+
+Trending tabs: `1`–`5` (Today → All) or `←`/`→` — `h`/`l`
+
+> Most actions are accessed via the **leader menu** (`Space`). This keeps the keymap minimal while providing a full command palette. The leader menu filters actions contextually — items that don't apply (e.g., Bookmark with no repo selected) are hidden.
+
 </details>
 
 ---
@@ -177,6 +203,33 @@ npm run build    # build dist/
 
 ---
 
+## Changelog
+
+### v0.8.2
+
+- Added automatic update checking against the npm registry
+- Added leader menu (Space) consolidating all contextual actions
+- Added update modal with Y/N/L (install now / skip / dismiss)
+- Added topic explorer, notifications panel, and saved searches overlay
+- Added activity graph toggle (commit chart fullscreen)
+- Added README viewer (full markdown rendering in TUI)
+- Added result auto-complete for search qualifiers (Tab)
+- Added PageUp/PageDown for quick navigation
+- Added Ctrl+X to clear history, Ctrl+C to clear all notifications
+- Improved export error handling and format selection
+- Updated keybindings reference
+
+### v0.8.1
+
+- Fixed postinstall to download Bun binary correctly on all platforms
+- Fixed zip asset names to match Bun's current release naming
+- Fixed zip parsing to use central directory instead of local file headers
+- Removed `vendor/` from npm package (Bun binary downloaded at install time)
+- Changed `postinstall` to use `node` instead of `bun run` (works without Bun pre-installed)
+- TUI now works on Node.js 20+ via bundled Bun binary
+
+---
+
 ## License
 
-MIT
+MIT

package/bin/ghfind.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * ghfind — npm bin entry point.
  * Requires Node.js >= 20 or Bun.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Terminal-native GitHub search — search, trending, bookmarks, history, deep-dive, compare, export, and more. All keyboard-driven, no browser needed.",
   "type": "module",
   "packageManager": "bun@1",

package/scripts/postinstall.js

@@ -1,106 +1,106 @@
-#!/usr/bin/env node
-/**
- * Postinstall script — ensures a Bun binary is available for ghfind.
- *
- * If vendor/bun or vendor/bun.exe already exists (bundled with the package),
- * this is a no-op. Otherwise, it attempts to download the correct binary
- * for the user's platform.
- */
-import { existsSync, mkdirSync, chmodSync, writeFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { platform, arch } from "os";
-import { inflateRawSync } from "zlib";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = join(__dirname, "..");
-const VENDOR_DIR = join(ROOT, "vendor");
-
-const bunName = platform() === "win32" ? "bun.exe" : "bun";
-const bunPath = join(VENDOR_DIR, bunName);
-
-// Already bundled — nothing to do
-if (existsSync(bunPath)) {
-  process.exit(0);
-}
-
-// Skip in CI/test environments
-if (process.env.GHFIND_SKIP_BUN === "1" || process.env.CI === "true") {
-  process.exit(0);
-}
-
-// Try to download
-const map = {
-  "win32-x64": "bun-windows-x64.zip",
-  "win32-arm64": "bun-windows-aarch64.zip",
-  "darwin-x64": "bun-darwin-x64.zip",
-  "darwin-arm64": "bun-darwin-aarch64.zip",
-  "linux-x64": "bun-linux-x64-musl.zip",
-  "linux-arm64": "bun-linux-aarch64-musl.zip",
-};
-
-const key = `${platform()}-${arch}`;
-const assetName = map[key];
-const version = "1.3.12";
-
-if (!assetName) {
-  console.error(`[ghfind] Unsupported platform: ${key}. Install Bun manually: https://bun.sh`);
-  process.exit(0);
-}
-
-const url = `https://github.com/oven-sh/bun/releases/download/bun-v${version}/${assetName}`;
-
-try {
-  mkdirSync(VENDOR_DIR, { recursive: true });
-  console.error(`[ghfind] Downloading Bun ${version} for ${key}...`);
-
-  const res = await fetch(url);
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-
-  const buffer = Buffer.from(await res.arrayBuffer());
-
-  // Find the central directory file header signature (PK\x01\x02)
-  const cdSig = "PK\x01\x02";
-  let cdOffset = buffer.indexOf(cdSig, 0);
-  while (cdOffset !== -1) {
-    const nameLen = buffer.readUInt16LE(cdOffset + 28);
-    const extraLen = buffer.readUInt16LE(cdOffset + 30);
-    const commentLen = buffer.readUInt16LE(cdOffset + 32);
-    const localHeaderOffset = buffer.readUInt32LE(cdOffset + 42);
-    const compSize = buffer.readUInt32LE(cdOffset + 20);
-    const compMethod = buffer.readUInt16LE(cdOffset + 10);
-    const nameStart = cdOffset + 46;
-    const fileName = buffer.subarray(nameStart, nameStart + nameLen).toString("utf8");
-
-    if (fileName.endsWith(bunName)) {
-      // Read the local file header to get the actual data offset
-      const localSig = buffer.readUInt32LE(localHeaderOffset);
-      if (localSig !== 0x04034b50) throw new Error("Invalid local file header");
-      const localNameLen = buffer.readUInt16LE(localHeaderOffset + 26);
-      const localExtraLen = buffer.readUInt16LE(localHeaderOffset + 28);
-      const dataOffset = localHeaderOffset + 30 + localNameLen + localExtraLen;
-
-      let fileData;
-      if (compMethod === 0) {
-        // Stored (no compression)
-        fileData = buffer.subarray(dataOffset, dataOffset + compSize);
-      } else {
-        // Deflated
-        fileData = inflateRawSync(buffer.subarray(dataOffset, dataOffset + compSize));
-      }
-
-      writeFileSync(bunPath, fileData);
-      if (platform() !== "win32") chmodSync(bunPath, 0o755);
-      console.error(`[ghfind] Bun installed to vendor/${bunName}`);
-      process.exit(0);
-    }
-
-    cdOffset = buffer.indexOf(cdSig, cdOffset + 4);
-  }
-
-  throw new Error("Bun binary not found in archive");
-} catch (err) {
-  console.error(`[ghfind] Failed to download Bun: ${err instanceof Error ? err.message : String(err)}`);
-  console.error("[ghfind] Install Bun manually: https://bun.sh/docs/install");
-  process.exit(0);
-}
+#!/usr/bin/env node
+/**
+ * Postinstall script — ensures a Bun binary is available for ghfind.
+ *
+ * If vendor/bun or vendor/bun.exe already exists (bundled with the package),
+ * this is a no-op. Otherwise, it attempts to download the correct binary
+ * for the user's platform.
+ */
+import { existsSync, mkdirSync, chmodSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { platform, arch } from "os";
+import { inflateRawSync } from "zlib";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+const VENDOR_DIR = join(ROOT, "vendor");
+
+const bunName = platform() === "win32" ? "bun.exe" : "bun";
+const bunPath = join(VENDOR_DIR, bunName);
+
+// Already bundled — nothing to do
+if (existsSync(bunPath)) {
+  process.exit(0);
+}
+
+// Skip in CI/test environments
+if (process.env.GHFIND_SKIP_BUN === "1" || process.env.CI === "true") {
+  process.exit(0);
+}
+
+// Try to download
+const map = {
+  "win32-x64": "bun-windows-x64.zip",
+  "win32-arm64": "bun-windows-aarch64.zip",
+  "darwin-x64": "bun-darwin-x64.zip",
+  "darwin-arm64": "bun-darwin-aarch64.zip",
+  "linux-x64": "bun-linux-x64-musl.zip",
+  "linux-arm64": "bun-linux-aarch64-musl.zip",
+};
+
+const key = `${platform()}-${arch}`;
+const assetName = map[key];
+const version = "1.3.12";
+
+if (!assetName) {
+  console.error(`[ghfind] Unsupported platform: ${key}. Install Bun manually: https://bun.sh`);
+  process.exit(0);
+}
+
+const url = `https://github.com/oven-sh/bun/releases/download/bun-v${version}/${assetName}`;
+
+try {
+  mkdirSync(VENDOR_DIR, { recursive: true });
+  console.error(`[ghfind] Downloading Bun ${version} for ${key}...`);
+
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+
+  const buffer = Buffer.from(await res.arrayBuffer());
+
+  // Find the central directory file header signature (PK\x01\x02)
+  const cdSig = "PK\x01\x02";
+  let cdOffset = buffer.indexOf(cdSig, 0);
+  while (cdOffset !== -1) {
+    const nameLen = buffer.readUInt16LE(cdOffset + 28);
+    const extraLen = buffer.readUInt16LE(cdOffset + 30);
+    const commentLen = buffer.readUInt16LE(cdOffset + 32);
+    const localHeaderOffset = buffer.readUInt32LE(cdOffset + 42);
+    const compSize = buffer.readUInt32LE(cdOffset + 20);
+    const compMethod = buffer.readUInt16LE(cdOffset + 10);
+    const nameStart = cdOffset + 46;
+    const fileName = buffer.subarray(nameStart, nameStart + nameLen).toString("utf8");
+
+    if (fileName.endsWith(bunName)) {
+      // Read the local file header to get the actual data offset
+      const localSig = buffer.readUInt32LE(localHeaderOffset);
+      if (localSig !== 0x04034b50) throw new Error("Invalid local file header");
+      const localNameLen = buffer.readUInt16LE(localHeaderOffset + 26);
+      const localExtraLen = buffer.readUInt16LE(localHeaderOffset + 28);
+      const dataOffset = localHeaderOffset + 30 + localNameLen + localExtraLen;
+
+      let fileData;
+      if (compMethod === 0) {
+        // Stored (no compression)
+        fileData = buffer.subarray(dataOffset, dataOffset + compSize);
+      } else {
+        // Deflated
+        fileData = inflateRawSync(buffer.subarray(dataOffset, dataOffset + compSize));
+      }
+
+      writeFileSync(bunPath, fileData);
+      if (platform() !== "win32") chmodSync(bunPath, 0o755);
+      console.error(`[ghfind] Bun installed to vendor/${bunName}`);
+      process.exit(0);
+    }
+
+    cdOffset = buffer.indexOf(cdSig, cdOffset + 4);
+  }
+
+  throw new Error("Bun binary not found in archive");
+} catch (err) {
+  console.error(`[ghfind] Failed to download Bun: ${err instanceof Error ? err.message : String(err)}`);
+  console.error("[ghfind] Install Bun manually: https://bun.sh/docs/install");
+  process.exit(0);
+}

package/src/bookmarks.ts

@@ -1,30 +1,17 @@
 /**
  * Bookmarks — saved repos with tags, persisted as JSON.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
 import type { Bookmark, Repo } from "./types";
-import { stateDir } from "./config";
+import { readJSON, writeJSON } from "./storage";
 
-const BOOKMARK_FILE = join(stateDir(), "bookmarks.json");
-
-function ensureDir() {
-  mkdirSync(stateDir(), { recursive: true });
-}
+const BOOKMARK_FILE = "bookmarks.json";
 
 function loadRaw(): Bookmark[] {
-  ensureDir();
-  try {
-    const raw = readFileSync(BOOKMARK_FILE, "utf-8");
-    return JSON.parse(raw) as Bookmark[];
-  } catch {
-    return [];
-  }
+  return readJSON<Bookmark[]>(BOOKMARK_FILE, []);
 }
 
 function saveRaw(bookmarks: Bookmark[]): void {
-  ensureDir();
-  writeFileSync(BOOKMARK_FILE, JSON.stringify(bookmarks, null, 2));
+  writeJSON(BOOKMARK_FILE, bookmarks);
 }
 
 /** Get all bookmarks, newest first. */

package/src/cli.ts

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 /** CLI entry point — routes between TUI browser and non-interactive modes. */
-import { parseQuery, applyFlagFilters, rankRepos, createGitHubSearch } from "./search";
-import { formatRepos, type ExportFormat } from "./export";
-import { formatLines, pipeExec, type FormatLine } from "./pipe";
+import { parseQuery, applyFlagFilters, rankRepos, createGitHubSearch, createTrendingSearch } from "./search";
+import { format as formatOutput, exportToFile, pipeExec, type Format, type ExportFormat, type FormatLine } from "./output";
 import { runWatch } from "./watch";
 import { runInitWizard } from "./init";
 import { readFileSync } from "fs";
@@ -158,13 +157,13 @@ Options:
   }
 
   // Determine output format
-  const format: ExportFormat | undefined =
+  const outputFormat: ExportFormat | undefined =
     flags.json ? "json" : flags.csv ? "csv" : flags.markdown ? "markdown" : undefined;
-  const isNonInteractive = format || flags.count || flags.format || flags.pipe || flags.watch;
+  const isNonInteractive = outputFormat || flags.count || flags.format || flags.pipe || flags.watch;
 
   // Non-interactive mode
   if (isNonInteractive) {
-    await runNonInteractive(flags, format);
+    await runNonInteractive(flags, outputFormat);
     return;
   }
 
@@ -172,65 +171,95 @@ Options:
   await launchBrowser();
 }
 
-async function runNonInteractive(flags: CLIFlags, format?: ExportFormat) {
-  const query = flags.query;
-  const provider = createGitHubSearch(undefined, flags.token ? [flags.token] : []);
-
-  // --watch mode
-  if (flags.watch) {
-    let tick = 0;
-    await runWatch(
-      { query, sort: flags.sort, limit: flags.limit, token: flags.token, intervalMs: flags.interval * 1000, trending: flags.trending },
-      (repos, delta) => {
-        tick++;
-        if (format) {
-          console.log(`[Watch #${tick}] ${repos.length} results (${delta >= 0 ? "+" : ""}${delta} since last check)`);
-          console.log(formatRepos(repos, format));
-        } else {
-          console.log(`[Watch #${tick}] ${repos.length} results — ${delta >= 0 ? "+" : ""}${delta} since last check`);
-        }
-      },
-      (err) => console.error(`[Watch error] ${err.message}`),
-    );
-    return;
-  }
-
-  // --pipe mode
-  if (flags.pipe) {
-    const parsed = applyFlagFilters(parseQuery(query), {});
-    const response = await provider.search(parsed, { limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token });
-    const repos = rankRepos(response.repos, flags.sort);
-    await pipeExec(repos, flags.pipe);
-    return;
-  }
+interface SearchContext {
+  query: string;
+  parsed: ReturnType<typeof parseQuery> & { raw: string };
+  provider: ReturnType<typeof createGitHubSearch>;
+}
 
-  // --format mode
-  if (flags.format) {
-    const parsed = applyFlagFilters(parseQuery(query), {});
-    const response = await provider.search(parsed, { limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token });
-    const repos = rankRepos(response.repos, flags.sort);
-    console.log(formatLines(repos, flags.format as FormatLine));
-    return;
-  }
+function buildSearchContext(flags: CLIFlags): SearchContext {
+  const parsed = applyFlagFilters(parseQuery(flags.query), {});
+  return {
+    query: flags.query,
+    parsed,
+    provider: createGitHubSearch(undefined, flags.token ? [flags.token] : []),
+  };
+}
 
-  // Standard search with format
-  const parsed = applyFlagFilters(parseQuery(query), {});
-  const response = await provider.search(parsed, {
-    limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token,
-  });
-  const repos = rankRepos(response.repos, flags.sort);
+async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
+  // Dispatch table: each handler receives shared context + flags, returns void.
+  const handlers: Record<string, (ctx: SearchContext) => Promise<void>> = {
+    trending: async (ctx) => {
+      const since = flags.since === "weekly" ? "weekly" : flags.since === "monthly" ? "monthly" : "daily";
+      const trendingSearch = createTrendingSearch();
+      const response = await trendingSearch.search(
+        { keywords: [], qualifiers: [], raw: "trending" },
+        { limit: 25, sort: "stars", json: false, verbose: false, trendingSince: since },
+      );
+      if (outputFormat) {
+        console.log(formatOutput(response.repos, outputFormat));
+      } else if (flags.count) {
+        console.log(response.totalCount);
+      } else {
+        for (const r of response.repos) {
+          console.log(r.fullName + "  ★ " + r.stars + "  ▲ +" + r.score + " " + since + "  ● " + (r.language ?? ""));
+        }
+      }
+    },
+    watch: async (ctx) => {
+      let tick = 0;
+      await runWatch(
+        { query: ctx.query, sort: flags.sort, limit: flags.limit, token: flags.token, intervalMs: flags.interval * 1000, trending: flags.trending },
+        (repos, delta) => {
+          tick++;
+          if (outputFormat) {
+            console.log(`[Watch #${tick}] ${repos.length} results (${delta >= 0 ? "+" : ""}${delta} since last check)`);
+            console.log(formatOutput(repos, outputFormat));
+          } else {
+            console.log(`[Watch #${tick}] ${repos.length} results — ${delta >= 0 ? "+" : ""}${delta} since last check`);
+          }
+        },
+        (err) => console.error(`[Watch error] ${err.message}`),
+      );
+    },
+    pipe: async (ctx) => {
+      const response = await ctx.provider.search(ctx.parsed, {
+        limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token,
+      });
+      const repos = rankRepos(response.repos, flags.sort);
+      await pipeExec(repos, flags.pipe!);
+    },
+    format: async (ctx) => {
+      const response = await ctx.provider.search(ctx.parsed, {
+        limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token,
+      });
+      const repos = rankRepos(response.repos, flags.sort);
+      console.log(formatOutput(repos, flags.format as Format));
+    },
+    search: async (ctx) => {
+      const response = await ctx.provider.search(ctx.parsed, {
+        limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token,
+      });
+      const repos = rankRepos(response.repos, flags.sort);
+      if (flags.count) {
+        console.log(response.totalCount);
+        return;
+      }
+      if (outputFormat) {
+        console.log(formatOutput(repos, outputFormat));
+      }
+    },
+  };
 
-  // --count
-  if (flags.count) {
-    console.log(response.totalCount);
-    return;
-  }
+  // Determine which handler to run
+  const key = flags.trending && !flags.watch ? "trending"
+    : flags.watch ? "watch"
+    : flags.pipe ? "pipe"
+    : flags.format ? "format"
+    : "search";
 
-  // --json, --csv, --markdown
-  if (format) {
-    console.log(formatRepos(repos, format));
-    return;
-  }
+  const ctx = buildSearchContext(flags);
+  await handlers[key](ctx);
 }
 
 main().catch((err) => {

package/src/config.ts

@@ -9,7 +9,7 @@
 import type { Config } from "./types";
 import { homedir } from "os";
 import { join } from "path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
 
 /** Directory for persistent state (history, bookmarks, session). */
 export function stateDir(): string {
@@ -27,7 +27,7 @@ export function cacheDir(): string {
 const DEFAULTS: Config = {
   defaultSort: "best-match",
   defaultLimit: 50,
-  theme: "tokyo-night",
+  theme: "premium-dark",  // New default: premium dark with sharp edges
   cacheTtlSeconds: 300,
   defaultTab: "search",
 };