github-search-cli 0.7.0 → 0.8.0

package/README.md

@@ -1,136 +1,118 @@
-# search-cli
+# ghfind
 
-> Browse, search, and trend GitHub repos from your terminal. No browser needed.
+> Search GitHub repos from your terminal. No browser needed.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/codersdfs/search-cli/main/demo.svg" alt="search-cli demo" width="100%">
+  <img src="https://raw.githubusercontent.com/codersdfs/search-cli/main/demo.svg" alt="ghfind demo" width="100%">
 </p>
 
 ---
 
-## Quick start
+## Install
 
 ```bash
-# Requires Bun (https://bun.sh)
 npm install -g github-search-cli
-
-# Launch the interactive TUI browser
-search-cli
-
-# Non-interactive search (pipe to jq, csvkit, etc.)
-search-cli "language:Rust stars:>10000" --json | jq '.[].fullName'
-search-cli "language:Zig" --count
-search-cli --trending --json --since weekly
 ```
 
-## CLI modes
+## Use
 
 ```bash
-search-cli "query" --json              # JSON array
-search-cli "query" --csv               # CSV
-search-cli "query" --markdown          # Markdown table
-search-cli "query" --count             # Just the number
-search-cli "query" --format urls       # One URL per line
-search-cli "query" --pipe open         # Open each in browser
-search-cli "query" --pipe clone        # Print clone commands
-search-cli --trending --json           # Trending as JSON
-search-cli --watch "query"             # Poll every 300s
+# TUI
+ghfind
+
+# pipe
+ghfind "language:Rust stars:>1000" --json | jq '.[].fullName'
+ghfind "language:Zig" --count
+ghfind --trending --json --since weekly
 ```
 
-### Shell completions
+### Non-interactive
 
 ```bash
-source <(search-cli --completion bash)   # Bash
-source <(search-cli --completion zsh)    # Zsh
-search-cli --completion fish | source    # Fish
+ghfind "query" --json        # JSON
+ghfind "query" --csv         # CSV
+ghfind "query" --markdown    # Markdown
+ghfind "query" --count       # count only
+ghfind "query" --format urls # one URL per line
+ghfind "query" --pipe open   # open in browser
+ghfind "query" --pipe clone  # clone commands
+ghfind --trending --json     # trending as JSON
+ghfind --watch "query"       # poll every 300s
 ```
 
-### `gh` extension
+### Completions
 
 ```bash
-gh extension install ./gh-search-cli
-gh search-cli "language:Rust"
+source <(ghfind --completion bash)
+source <(ghfind --completion zsh)
+ghfind --completion fish | source
 ```
 
 ---
 
 ## Features
 
-| Category | What you get |
-|----------|-------------|
-| **Search** | Free-text + qualifiers (`language:`, `stars:`, `topic:`), sort by stars/updated/forks, Tab auto-complete |
-| **Trending** | Browse GitHub trending by day/week/month/year, filter by language |
-| **Memory** | Persistent history (`Ctrl+R`), bookmarks (`b`/`B`), saved searches (`Ctrl+S`/`Ctrl+O`), session restore |
-| **Deep-dive** | Per-repo detail: languages, top contributors, README preview (`d`) |
-| **Compare** | Select 2+ repos and compare side-by-side (`c`/`C`) |
-| **Explore** | Browse popular GitHub topics (`E`) |
-| **Export** | JSON, CSV, Markdown, plain text (`Ctrl+E`) |
-| **Shell** | Pipe-friendly output, `--watch` mode, shell completions, Docker |
-| **Delight** | 3 themes (Tokyo Night, Dracula, Monokai), animated status bar, clipboard share, startup tips |
+<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>Watch</b></td><td><code>--watch</code> — poll for new results</td></tr>
+</table>
 
 <details>
-<summary><b>⌨️ Full keybindings</b></summary>
-
-### Main view
+<summary>Keybindings</summary>
 
 | Key | Action |
 |-----|--------|
-| `/` | Focus search input |
-| `Enter` | Execute search / open repo |
-| `↑`/`↓` / `j`/`k` | Navigate results |
+| `/` | Focus search |
+| `Enter` | Search / open repo |
+| `↑`/`↓` / `j`/`k` | Navigate |
 | `t` | Toggle search / trending |
 | `s` | Cycle sort |
 | `l` | Cycle limit |
 | `r` | Refresh |
-| `g` | Toggle activity graph |
-| `d` | Toggle repo deep-dive |
-| `o` | Open repo in browser |
-| `b` / `B` | Toggle bookmark / open bookmarks |
-| `c` / `C` | Toggle compare list / show comparison |
-| `E` | Open topic explorer |
+| `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 overlay |
-| `q` | Quit |
-
-### Overlays
-
-| Key | Action |
-|-----|--------|
-| `Ctrl+R` | Search history |
-| `Ctrl+S` | Save current search |
-| `Ctrl+O` | Saved searches panel |
-| `Ctrl+E` | Export results |
+| `?` / `Ctrl+H` | Help |
+| `Ctrl+R` | History |
+| `Ctrl+S` / `Ctrl+O` | Save / open searches |
+| `Ctrl+E` | Export |
 | `Ctrl+N` | Notifications |
-| `Ctrl+P` | Share repo (copy to clipboard) |
-| `PageDown` / `Ctrl+F` | Next page |
+| `Ctrl+P` | Share |
 | `Esc` | Close overlay |
+| `q` | Quit |
 
-### Trending mode
-
-| Key | Action |
-|-----|--------|
-| `1`–`5` | Switch tab (Today → Week → Month → Year → All) |
-| `←`/`→` / `h`/`l` | Navigate tabs |
+Trending tabs: `1`–`5` (Today → All) or `←`/`→` / `h`/`l`
 </details>
 
 ---
 
 ## Search syntax
 
-```text
+```
 language:Rust stars:>1000 topic:cli
 "machine learning" language:Python stars:>5000
 topic:cli -language:JavaScript
 org:rust-lang language:Rust
 ```
 
-Supported qualifiers: `language:`, `stars:`, `fork:`, `archived:`, `topic:`, `user:`, `org:`, `repo:`, `updated:`, `pushed:`, `visibility:`, `license:`, `created:`, `size:`, `in:`. Prefix with `-` to exclude.
+Prefix with `-` to exclude. Supported: `language`, `stars`, `fork`, `archived`, `topic`, `user`, `org`, `repo`, `updated`, `pushed`, `visibility`, `license`, `created`, `size`, `in`.
 
 ---
 
-## Configuration
+## Config
 
-`~/.config/search-cli/config.json` (created automatically):
+`~/.config/ghfind/config.json` (auto-created, or run `ghfind init`):
 
 ```json
 {
@@ -141,43 +123,23 @@ Supported qualifiers: `language:`, `stars:`, `fork:`, `archived:`, `topic:`, `us
 }
 ```
 
-Or run `search-cli init` for the interactive setup wizard.
-
-Environment variables: `GITHUB_TOKEN`, `SEARCH_CLI_CONFIG`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`.
+Env: `GITHUB_TOKEN`, `GHFIND_CONFIG`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`
 
 ---
 
-## Install from source
+## From source
 
 ```bash
 git clone https://github.com/codersdfs/search-cli.git
-cd search-cli
-bun install
-bun start              # Launch TUI
-bun test               # 104 tests
-bun run build          # Compile binary → dist/
+cd ghfind
+npm install
+npm start    # TUI
+npm test     # 100+ tests
+npm run build
 ```
 
 ---
 
-## Design
-
-```
-CLI → QueryBuilder → Provider → Normalizer → Ranking → TUI / stdout
-```
-
-| Layer | File | Job |
-|-------|------|-----|
-| Entry | `src/cli.ts` | Arg parsing, routes to TUI or stdout |
-| TUI | `src/tui.ts` | Interactive browser (OpenTUI) |
-| Query | `src/query.ts` | Parse keywords/qualifiers |
-| Provider | `src/provider.ts` | GitHub REST API with caching + token rotation |
-| Types | `src/types.ts` | Shared interfaces |
-
-The `SearchProvider` interface is the extension point for alternative backends (GitLab, local index, AI retriever).
-
----
-
 ## License
 
-MIT
+MIT

package/bin/ghfind.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * ghfind — npm bin entry point.
+ * Requires Node.js >= 20.
+ */
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+try {
+  await import("../src/cli.ts");
+} catch (err) {
+  console.error("Failed to start ghfind. Node.js >= 20 required.");
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}

package/completions/{search-cli.bash → ghfind.bash}

@@ -1,7 +1,7 @@
-# search-cli bash completion
-# Source: source <(search-cli --completion bash)
+# ghfind bash completion
+# Source: source <(ghfind --completion bash)
 
-_search_cli() {
+_ghfind() {
   local cur prev opts
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
@@ -40,4 +40,4 @@ _search_cli() {
   COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
   return 0
 }
-complete -F _search_cli search-cli
+complete -F _ghfind ghfind

package/completions/ghfind.fish

@@ -0,0 +1,19 @@
+# ghfind fish completion
+# Source: source (ghfind --completion fish | psub)
+
+complete -c ghfind -l json -d "JSON output"
+complete -c ghfind -l csv -d "CSV output"
+complete -c ghfind -l markdown -d "Markdown table output"
+complete -c ghfind -l count -d "Only result count"
+complete -c ghfind -l limit -d "Max results" -r
+complete -c ghfind -l sort -d "Sort strategy" -r -f -a "best-match stars updated forks"
+complete -c ghfind -l token -d "GitHub token" -r
+complete -c ghfind -l trending -d "Trending mode"
+complete -c ghfind -l since -d "Trending period" -r -f -a "daily weekly monthly"
+complete -c ghfind -l pipe -d "Pipe target" -r -f -a "clone open"
+complete -c ghfind -l format -d "Output format" -r -f -a "urls names ssh-urls clone-commands ids"
+complete -c ghfind -l watch -d "Watch mode"
+complete -c ghfind -l interval -d "Watch interval seconds" -r
+complete -c ghfind -l version -d "Print version"
+complete -c ghfind -l help -d "Print help"
+complete -c ghfind -l completion -d "Shell" -r -f -a "bash zsh fish"

package/completions/{search-cli.zsh → ghfind.zsh}

@@ -1,27 +1,27 @@
-# search-cli zsh completion
-# Source: source <(search-cli --completion zsh)
-
-_search_cli() {
-  local -a opts
-  opts=(
-    '--json[JSON output]'
-    '--csv[CSV output]'
-    '--markdown[Markdown table output]'
-    '--count[Only result count]'
-    '--limit[Max results]:limit:'
-    '--sort[Sort strategy]:(best-match stars updated forks)'
-    '--token[GitHub token]:token:'
-    '--trending[Trending mode]'
-    '--since[Trending period]:(daily weekly monthly)'
-    '--pipe[Pipe target]:(clone open)'
-    '--format[Output format]:(urls names ssh-urls clone-commands ids)'
-    '--watch[Watch mode]'
-    '--interval[Watch interval seconds]:seconds:'
-    '--version[Print version]'
-    '--help[Print help]'
-    '--completion[Shell]:(bash zsh fish)'
-  )
-  _arguments "${opts[@]}" '*:query:'
-}
-
-compdef _search_cli search-cli
+# ghfind zsh completion
+# Source: source <(ghfind --completion zsh)
+
+_ghfind() {
+  local -a opts
+  opts=(
+    '--json[JSON output]'
+    '--csv[CSV output]'
+    '--markdown[Markdown table output]'
+    '--count[Only result count]'
+    '--limit[Max results]:limit:'
+    '--sort[Sort strategy]:(best-match stars updated forks)'
+    '--token[GitHub token]:token:'
+    '--trending[Trending mode]'
+    '--since[Trending period]:(daily weekly monthly)'
+    '--pipe[Pipe target]:(clone open)'
+    '--format[Output format]:(urls names ssh-urls clone-commands ids)'
+    '--watch[Watch mode]'
+    '--interval[Watch interval seconds]:seconds:'
+    '--version[Print version]'
+    '--help[Print help]'
+    '--completion[Shell]:(bash zsh fish)'
+  )
+  _arguments "${opts[@]}" '*:query:'
+}
+
+compdef _ghfind ghfind

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "github-search-cli",
-  "version": "0.7.0",
-  "description": "Terminal-native GitHub browser — search, trending, bookmarks, history, deep-dive, compare, export, and more. All keyboard-driven, no browser needed.",
+  "version": "0.8.0",
+  "description": "Terminal-native GitHub search — search, trending, bookmarks, history, deep-dive, compare, export, and more. All keyboard-driven, no browser needed.",
   "type": "module",
   "bin": {
-    "search-cli": "bin/search-cli.js"
+    "ghfind": "bin/ghfind.js"
   },
   "files": [
     "bin/",
@@ -16,19 +16,27 @@
   ],
   "scripts": {
     "start": "bun run src/cli.ts",
-    "build": "bun run scripts/build.ts",
-    "prepublishOnly": "bun run build",
-    "test": "bun test",
-    "dev": "bun run --watch src/tui.ts"
+    "build": "tsup src/cli.ts --format esm --target node20 --out-dir dist --external @opentui/core",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "dev": "bun run --watch src/tui.ts",
+    "format:check": "prettier --check .",
+    "format": "prettier --write ."
   },
   "dependencies": {
     "@opentui/core": "^0.4.3"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "prettier": "^3.2.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
   },
   "engines": {
-    "bun": ">=1.0"
+    "node": ">=20.0.0"
   },
   "repository": {
     "type": "git",

package/src/bookmarks.ts

@@ -1,69 +1,69 @@
-/**
- * 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.ts";
-import { stateDir } from "./config.ts";
-
-const BOOKMARK_FILE = join(stateDir(), "bookmarks.json");
-
-function ensureDir() {
-  mkdirSync(stateDir(), { recursive: true });
-}
-
-function loadRaw(): Bookmark[] {
-  ensureDir();
-  try {
-    const raw = readFileSync(BOOKMARK_FILE, "utf-8");
-    return JSON.parse(raw) as Bookmark[];
-  } catch {
-    return [];
-  }
-}
-
-function saveRaw(bookmarks: Bookmark[]): void {
-  ensureDir();
-  writeFileSync(BOOKMARK_FILE, JSON.stringify(bookmarks, null, 2));
-}
-
-/** Get all bookmarks, newest first. */
-export function getBookmarks(): Bookmark[] {
-  return loadRaw().sort((a, b) => b.savedAt - a.savedAt);
-}
-
-/** Check if a repo is bookmarked by fullName. */
-export function isBookmarked(fullName: string): boolean {
-  return loadRaw().some((b) => b.repo.fullName === fullName);
-}
-
-/** Toggle bookmark: add if not present, remove if present. Returns new state. */
-export function toggleBookmark(repo: Repo, tags: string[] = []): boolean {
-  const bookmarks = loadRaw();
-  const idx = bookmarks.findIndex((b) => b.repo.fullName === repo.fullName);
-  if (idx >= 0) {
-    bookmarks.splice(idx, 1);
-    saveRaw(bookmarks);
-    return false; // removed
-  }
-  bookmarks.push({ repo, savedAt: Date.now(), tags });
-  saveRaw(bookmarks);
-  return true; // added
-}
-
-/** Remove a bookmark by fullName. */
-export function removeBookmark(fullName: string): void {
-  const bookmarks = loadRaw().filter((b) => b.repo.fullName !== fullName);
-  saveRaw(bookmarks);
-}
-
-/** Search bookmarks by text (matches name, description, tags). */
-export function searchBookmarks(query: string): Bookmark[] {
-  const q = query.toLowerCase();
-  return getBookmarks().filter(
-    (b) =>
-      b.repo.fullName.toLowerCase().includes(q) ||
-      (b.repo.description ?? "").toLowerCase().includes(q) ||
-      b.tags.some((t) => t.toLowerCase().includes(q)),
-  );
-}
+/**
+ * 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";
+
+const BOOKMARK_FILE = join(stateDir(), "bookmarks.json");
+
+function ensureDir() {
+  mkdirSync(stateDir(), { recursive: true });
+}
+
+function loadRaw(): Bookmark[] {
+  ensureDir();
+  try {
+    const raw = readFileSync(BOOKMARK_FILE, "utf-8");
+    return JSON.parse(raw) as Bookmark[];
+  } catch {
+    return [];
+  }
+}
+
+function saveRaw(bookmarks: Bookmark[]): void {
+  ensureDir();
+  writeFileSync(BOOKMARK_FILE, JSON.stringify(bookmarks, null, 2));
+}
+
+/** Get all bookmarks, newest first. */
+export function getBookmarks(): Bookmark[] {
+  return loadRaw().sort((a, b) => b.savedAt - a.savedAt);
+}
+
+/** Check if a repo is bookmarked by fullName. */
+export function isBookmarked(fullName: string): boolean {
+  return loadRaw().some((b) => b.repo.fullName === fullName);
+}
+
+/** Toggle bookmark: add if not present, remove if present. Returns new state. */
+export function toggleBookmark(repo: Repo, tags: string[] = []): boolean {
+  const bookmarks = loadRaw();
+  const idx = bookmarks.findIndex((b) => b.repo.fullName === repo.fullName);
+  if (idx >= 0) {
+    bookmarks.splice(idx, 1);
+    saveRaw(bookmarks);
+    return false; // removed
+  }
+  bookmarks.push({ repo, savedAt: Date.now(), tags });
+  saveRaw(bookmarks);
+  return true; // added
+}
+
+/** Remove a bookmark by fullName. */
+export function removeBookmark(fullName: string): void {
+  const bookmarks = loadRaw().filter((b) => b.repo.fullName !== fullName);
+  saveRaw(bookmarks);
+}
+
+/** Search bookmarks by text (matches name, description, tags). */
+export function searchBookmarks(query: string): Bookmark[] {
+  const q = query.toLowerCase();
+  return getBookmarks().filter(
+    (b) =>
+      b.repo.fullName.toLowerCase().includes(q) ||
+      (b.repo.description ?? "").toLowerCase().includes(q) ||
+      b.tags.some((t) => t.toLowerCase().includes(q)),
+  );
+}