github-search-cli 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 search-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# search-cli
+
+> The terminal home for GitHub discovery — search, trending, bookmarks, and deep-dive repo exploration, all without touching a browser.
+
+```bash
+npx github-search-cli    # TUI browser
+search-cli "language:Rust stars:>1000" --json   # CLI mode
+search-cli --version
+```
+
+---
+
+## Features
+
+| Category | Features |
+|----------|----------|
+| **Search** | Free-text + qualifiers (`language:`, `stars:`, `topic:`, etc.), sort by stars/updated/forks, auto-complete on Tab |
+| **Trending** | Browse GitHub trending by day/week/month/year, language filter |
+| **Memory** | Persistent search history (`Ctrl+R`), bookmarks (`b`/`B`), saved searches (`Ctrl+S`/`Ctrl+O`), session restore |
+| **Deep-dive** | Per-repo detail: languages bar, 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 `--json`/`--csv`/`--markdown`, `--format urls`, `--pipe open/clone`, `--watch`, shell completions |
+| **Delight** | 3 themes (Tokyo Night, Dracula, Monokai), animated status bar, notification center, clipboard share, startup tips |
+
+---
+
+## Quick start
+
+```bash
+# Requires Bun (https://bun.sh)
+npm install -g github-search-cli
+# or: bun 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
+```
+
+---
+
+## TUI keyboard shortcuts
+
+### Main view
+
+| Key | Action |
+|-----|--------|
+| `/` | Focus search input |
+| `Enter` | Execute search / open repo |
+| `↑`/`↓` / `j`/`k` | Navigate results |
+| `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 |
+| `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+N` | Notifications |
+| `Ctrl+P` | Share repo (copy to clipboard) |
+| `PageDown` / `Ctrl+F` | Next page |
+| `Esc` | Close overlay |
+
+### Trending mode
+
+| Key | Action |
+|-----|--------|
+| `1`–`5` | Switch tab (Today → Week → Month → Year → All) |
+| `←`/`→` / `h`/`l` | Navigate tabs |
+
+---
+
+## Search syntax
+
+```
+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.
+
+---
+
+## CLI modes (non-interactive)
+
+```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
+```
+
+### Shell completions
+
+```bash
+source <(search-cli --completion bash)   # Bash
+source <(search-cli --completion zsh)    # Zsh
+search-cli --completion fish | source    # Fish
+```
+
+### `gh` extension
+
+```bash
+gh extension install ./gh-search-cli
+gh search-cli "language:Rust"
+```
+
+---
+
+## Configuration
+
+`~/.config/search-cli/config.json` (created automatically):
+
+```json
+{
+  "defaultSort": "stars",
+  "defaultLimit": 50,
+  "theme": "tokyo-night",
+  "githubToken": "ghp_..."
+}
+```
+
+Or run `search-cli init` for the interactive setup wizard.
+
+Environment variables: `GITHUB_TOKEN`, `SEARCH_CLI_CONFIG`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`.
+
+---
+
+## 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).
+
+---
+
+## Install 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/
+```
+
+---
+
+## License
+
+MIT

package/bin/search-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+/**
+ * search-cli — npm bin entry point.
+ * Requires Bun (https://bun.sh) to run.
+ */
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, "..", "src", "cli.ts");
+
+try {
+  await import(cli);
+} catch (err) {
+  console.error("Failed to start search-cli. Is Bun installed? (https://bun.sh)");
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}

package/completions/search-cli.bash

@@ -0,0 +1,43 @@
+# search-cli bash completion
+# Source: source <(search-cli --completion bash)
+
+_search_cli() {
+  local cur prev opts
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  opts="--json --csv --markdown --count --limit --sort --token --trending --since --pipe --format --watch --interval --version --help --completion"
+
+  case "${prev}" in
+    --sort)
+      COMPREPLY=( $(compgen -W "best-match stars updated forks" -- "${cur}") )
+      return 0
+      ;;
+    --since)
+      COMPREPLY=( $(compgen -W "daily weekly monthly" -- "${cur}") )
+      return 0
+      ;;
+    --pipe)
+      COMPREPLY=( $(compgen -W "clone open" -- "${cur}") )
+      return 0
+      ;;
+    --format)
+      COMPREPLY=( $(compgen -W "urls names ssh-urls clone-commands ids" -- "${cur}") )
+      return 0
+      ;;
+    --completion)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "${cur}") )
+      return 0
+      ;;
+    --limit|--interval)
+      return 0
+      ;;
+    *)
+      ;;
+  esac
+
+  COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+  return 0
+}
+complete -F _search_cli search-cli

package/completions/search-cli.fish

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

package/completions/search-cli.zsh

@@ -0,0 +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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "github-search-cli",
+  "version": "0.6.0",
+  "description": "Terminal-native GitHub browser — 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"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "completions/",
+    "LICENSE",
+    "README.md"
+  ],
+  "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"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "engines": {
+    "bun": ">=1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codersdfs/search-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/codersdfs/search-cli/issues"
+  },
+  "homepage": "https://github.com/codersdfs/search-cli#readme",
+  "keywords": [
+    "github",
+    "cli",
+    "search",
+    "trending",
+    "terminal",
+    "tui",
+    "browser",
+    "developer-tools",
+    "opentui"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bookmarks.ts

@@ -0,0 +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)),
+  );
+}

package/src/cache.ts

@@ -0,0 +1,64 @@
+/**
+ * In-memory LRU cache with TTL for API responses.
+ * 
+ * ponytail: in-memory only. Disk cache adds ~70 lines for marginal benefit
+ * (re-cache on restart rather than re-fetch). Add disk layer if cache-miss
+ * rate after restart becomes a problem.
+ */
+import type { CacheEntry } from "./types.ts";
+
+const MAX_SIZE = 50;
+
+export class MemoryCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+
+  constructor(private defaultTtlMs: number = 300_000) {}
+
+  /** Build a normalized cache key. */
+  static key(...parts: string[]): string {
+    return parts.join("::").toLowerCase().replace(/\s+/g, " ");
+  }
+
+  /** Get entry if not expired. Returns null on miss or expiry. */
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (Date.now() - entry.cachedAt > entry.ttlMs) {
+      this.cache.delete(key);
+      return null;
+    }
+    // Move to most-recently-used position
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.data;
+  }
+
+  /** Set entry with optional per-entry TTL. */
+  set(key: string, data: T, ttlMs?: number): void {
+    if (this.cache.size >= MAX_SIZE) {
+      // Evict least-recently-used (first inserted key)
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) this.cache.delete(firstKey);
+    }
+    this.cache.set(key, {
+      data,
+      cachedAt: Date.now(),
+      ttlMs: ttlMs ?? this.defaultTtlMs,
+    });
+  }
+
+  /** Remove entry. */
+  delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  /** Clear all entries. */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /** Number of entries in cache. */
+  get size(): number {
+    return this.cache.size;
+  }
+}