github-search-cli 9.5.1 → 9.7.0

package/CHANGELOG.md

@@ -6,6 +6,101 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
+## [9.7.0] — 2026-09-19 (released)
+
+### Added
+
+- **CLI parity with the MCP tools** — the three MCP-only capabilities are now
+  first-class CLI commands:
+  - `ghfind deep-dive <owner/repo> [--json]` — language breakdown, top
+    contributors, and a README excerpt (previously MCP-only; the agent skill
+    doc told agents to `curl` instead).
+  - `ghfind --compare` accepts `--json|--csv|--markdown` (previously
+    text-only) and reports repos that failed to resolve; it exits non-zero
+    when fewer than 2 repos resolve.
+  - Trending language filter on the CLI: `ghfind trending <lang>` (the form
+    the README already advertised), `ghfind --trending <lang>`, and
+    `ghfind --trending --language <lang>` — validated against the same
+    accepted-language list as the MCP tool.
+- `ghfind deep-dive --json` exposes a structured payload (language percents,
+  contributor counts, raw README) suitable for agents and scripting.
+
+### Changed
+
+- The MCP server now shares its repo-ref parsing, trending-language
+  validation, and deep-dive data pipeline with the CLI via new seams in
+  `deepdive.ts` and `search.ts` (no protocol behavior change).
+
+### Fixed
+
+- **`ghfind mcp` failed to typecheck** — `processServerLine` declared `msg`
+  as a `let` binding, so TypeScript's aliased-conditional narrowing did not
+  apply and every `respond`/`respondError` call site errored on
+  `JsonRpcId | undefined`. HEAD did not compile. The id is now extracted
+  into a `const` before the notification check; runtime behavior is
+  unchanged (all 31 MCP tests pass against the previous behavior).
+- **Deep-dive ran on a zeroed repo stub** — `ghfind deep-dive a/b --json`
+  reported `stars: 0`, `description: null`, and no timestamps because the
+  repo ref was never resolved. Both the CLI and the `ghfind_deep_dive` MCP
+  tool now fetch real repo metadata first (a 404 exits with
+  `Repo not found: owner/name`; network failures still degrade gracefully
+  to the stub).
+
+---
+
+## [9.6.0] — 2026-09-18 (released)
+
+### Added
+
+- **MCP server (beta)** (`ghfind mcp`) — ghfind now speaks the
+  [Model Context Protocol](https://modelcontextprotocol.io): any MCP client
+  (Claude Code, Cursor, Codex, …) can call GitHub search as tools over stdio.
+  Zero new dependencies — the server is a small JSON-RPC 2.0 layer over the
+  existing modules. Nine tools: `ghfind_search_repos`, `ghfind_trending`,
+  `ghfind_npm_packages`, `ghfind_org_profile`, `ghfind_user_profile`,
+  `ghfind_compare_repos`, `ghfind_deep_dive`, `ghfind_bookmarked_releases`,
+  and `ghfind_skill`. Implements the 2025-06-18 lifecycle (initialize →
+  initialized notification → operation), speaks 2025-06-18 / 2025-03-26 /
+  2024-11-05, reports tool failures as `isError` results per spec, and logs
+  agent searches into the TUI history. `ghfind mcp --token <t>` pins a token;
+  otherwise config/`GITHUB_TOKEN` applies.
+- **Agent skill (beta)** (`ghfind skill [name]`) — a token-efficient CLI usage guide
+  for coding agents (search syntax, flags, rate limits, token-efficiency
+  tips) so they stop parsing `--help`. Bare `ghfind skill` lists the catalog;
+  the registry (`src/agent-skill.ts`) is generic, so third parties can
+  register their own skills alongside the built-in `ghfind-cli` one.
+- **Trending language filter** — `SearchOptions.trendingLanguage` and the
+  `ghfind_trending` MCP tool accept a github.com/trending language slug
+  (`rust`, `python`, …); `buildTrendingUrl` validates against the known
+  language list and drops unknown slugs instead of scraping an error page.
+- **`NO_COLOR` support** — `ghfind --doctor` no longer emits ANSI color
+  codes when `NO_COLOR` is set (any value, per
+  [no-color.org](https://no-color.org/)) or when stdout is not a TTY.
+- **curl installer** (`scripts/install.sh`) — downloads the standalone
+  binary for the detected platform from GitHub Releases, verifies it
+  against the release's `SHA256SUMS.txt`, installs to `~/.local/bin` or
+  `/usr/local/bin` (overridable with `GHFIND_INSTALL_DIR`, never needs
+  sudo), and prints a PATH hint when needed.
+- **`SHA256SUMS.txt` on every release** — new `checksums` job in the
+  release workflow merges all platform binaries' checksums into one
+  file attached to the GitHub Release; the curl installer and package
+  maintainers verify against it.
+- **Community health files** — `SECURITY.md` (private vulnerability
+  reporting), `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1), and
+  `SUPPORT.md` (routes users to `--doctor`, issues, and discussions).
+
+### Fixed
+
+- **`scripts/brew.rb` formula was stale and broken** — pointed at the
+  wrong repo (`frank/search-cli`), version 0.1.0, and `search-cli-*`
+  asset names that never matched the release artifacts. Now targets
+  `codersdfs/search-cli` releases with the correct `ghfind-*` asset
+  names (plus linux-arm64), a livecheck block, and a version-pinning
+  test. Still a template: SHA256 placeholders are filled from
+  `SHA256SUMS.txt` when the tap lands.
+
+---
+
 ## [9.5.1] — 2026-09-15
 
 ### Fixed

package/README.md

@@ -26,23 +26,31 @@
 npm install -g github-search-cli
 ```
 
+Or via the **curl installer** (Linux/macOS — downloads the standalone
+binary, verifies its SHA256 against the release checksums, no Node
+needed):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/codersdfs/search-cli/main/scripts/install.sh | sh
+```
+
 Or grab a **standalone binary** (no Node.js needed) from [GitHub Releases](https://github.com/codersdfs/search-cli/releases) — `ghfind-<os>-<arch>` executables for Linux, macOS, and Windows.
 
 ## Why ghfind?
 
-|                                            | `ghfind` | `gh search` (GitHub CLI) | `hub` |
-| ------------------------------------------ | -------- | ------------------------ | ----- |
-| Repo search + qualifiers                   | ✅       | ✅                       | ❌    |
-| Trending repos (day/week/month/year)       | ✅       | ❌                       | ❌    |
-| Full-screen TUI, keyboard-driven           | ✅       | ❌                       | ❌    |
-| Bookmarks, tags & release tracking         | ✅       | ❌                       | ❌    |
-| Side-by-side repo compare                  | ✅       | ❌                       | ❌    |
-| Deep-dive (README, contributors, activity) | ✅       | ❌                       | ❌    |
-| npm package search                         | ✅       | ❌                       | ❌    |
-| Org profile                                | ✅       | ✅                       | ❌    |
-| User profile                               | ✅       | ❌                       | ❌    |
-| Pipeable JSON / CSV / Markdown export      | ✅       | JSON only                | ❌    |
-| No login required                          | ✅       | ❌                       | ❌    |
+|                                             | `ghfind` | `gh search` (GitHub CLI) | `hub` |
+| ------------------------------------------- | -------- | ------------------------ | ----- |
+| Repo search + qualifiers                    | ✅       | ✅                       | ❌    |
+| Trending repos (day/week/month/year)        | ✅       | ❌                       | ❌    |
+| Full-screen TUI, keyboard-driven            | ✅       | ❌                       | ❌    |
+| Bookmarks, tags & release tracking          | ✅       | ❌                       | ❌    |
+| Side-by-side repo compare (JSON/CSV/MD)     | ✅       | ❌                       | ❌    |
+| Deep-dive (languages, contributors, README) | ✅       | ❌                       | ❌    |
+| npm package search                          | ✅       | ❌                       | ❌    |
+| Org profile                                 | ✅       | ✅                       | ❌    |
+| User profile                                | ✅       | ❌                       | ❌    |
+| Pipeable JSON / CSV / Markdown export       | ✅       | JSON only                | ❌    |
+| No login required                           | ✅       | ❌                       | ❌    |
 
 > **No separate runtime needed!** Only requires Node.js 20+. The TUI needs Bun,
 > which is downloaded automatically at install time. Non-interactive modes work
@@ -80,12 +88,49 @@ 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 trending rust --json  # trending, filtered by language
 ghfind --watch "query"       # poll every 300s
 ghfind --releases            # new releases for bookmarked repos
 ghfind --compare a/b c/d     # side-by-side comparison
+ghfind --compare a/b c/d --json # comparison as JSON|CSV|Markdown
+ghfind deep-dive a/b --json  # deep-dive: languages, contributors, README
 ghfind pkg "query" --json    # npm package search as JSON
 ```
 
+## Use with AI agents
+
+ghfind speaks the [Model Context Protocol](https://modelcontextprotocol.io) —
+any MCP client (Claude Code, Cursor, Codex, …) can call its GitHub search
+as tools:
+
+```bash
+claude mcp add ghfind -- ghfind mcp
+```
+
+or in your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "ghfind": { "command": "ghfind", "args": ["mcp"] }
+  }
+}
+```
+
+Exposed tools: `ghfind_search_repos`, `ghfind_trending`,
+`ghfind_npm_packages`, `ghfind_org_profile`, `ghfind_user_profile`,
+`ghfind_compare_repos`, `ghfind_deep_dive`, `ghfind_bookmarked_releases`,
+and `ghfind_skill` (a token-efficient CLI usage guide for agents).
+Unauthenticated requests are rate-limited to 60/hr — set `GITHUB_TOKEN`
+in the environment for 5,000/hr.
+
+CLI-first agents can skip MCP entirely:
+
+```bash
+ghfind skill            # list agent skills
+ghfind skill ghfind-cli # print the token-efficient CLI guide
+```
+
 ### Completions
 
 ```bash
@@ -117,6 +162,8 @@ ghfind --completion fish | source
 <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>
+<tr><td><b>MCP server</b></td><td><code>ghfind mcp</code> — GitHub search as tools for AI agents (Claude Code, Cursor, …)</td></tr>
+<tr><td><b>Agent skill</b></td><td><code>ghfind skill</code> — token-efficient CLI usage guide for coding agents</td></tr>
 </table>
 
 <details>
@@ -224,7 +271,7 @@ Prefix with `-` to exclude. Supported: `language`, `stars`, `fork`, `archived`,
 }
 ```
 
-Env: `GITHUB_TOKEN`, `GHFIND_CONFIG`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`
+Env: `GITHUB_TOKEN`, `GHFIND_CONFIG`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `NO_COLOR` (disables colored `--doctor` output, per [no-color.org](https://no-color.org/))
 
 ---
 
@@ -237,14 +284,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 295 tests
+bun test         # 355 tests
 bun run check    # format check + tests — the green gate
 bun run build    # build dist/
 
 # Or with npm
 npm install
 npm start        # TUI (requires Node 20+)
-npm test         # 295 tests
+npm test         # 355 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -257,22 +304,25 @@ npm run build    # build dist/
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
-### v9.5.1
+### v9.7.0
 
-- Fixed landing-screen keys leaking into the main view — `/`, `Space`, `t`, `c`, `?`, `q` all double-fired; `b` on the landing screen now opens Bookmarks
-- Fixed the update panel clipping the changelog — release notes are now scrollable (`↑↓`/`j`/`k`, `PgUp`/`PgDn`, `Home`/`End`) in a taller panel
+- **CLI parity with the MCP tools** — `ghfind deep-dive <owner/repo>` (languages, contributors, README excerpt, `--json`), `ghfind --compare` with `--json|--csv|--markdown`, and a trending language filter (`ghfind trending rust`, `--trending <lang>`)
+- **Deep-dive metadata fix** — real stars, description, and topics are fetched first instead of a zeroed stub; a 404 exits with `Repo not found`
+- Fixed `ghfind mcp` failing to typecheck (JSON-RPC id narrowing; runtime behavior unchanged)
+- The MCP server and CLI now share repo-ref parsing, language validation, and the deep-dive pipeline
 
-### v9.5.0
+### v9.6.0
 
-- New `ghfind user <name>` command — user profiles like `ghfind org`: repos, total stars/forks, followers, top languages, top repos
-- Supports `--json`, `--csv`, `--markdown`, `--count`, `--limit`, `--token`; `@` prefix accepted
-- Fixed `ghfind org` mangling multi-word names with dashes
+- **MCP server (beta)** — `ghfind mcp` turns ghfind into a tool server: Claude Code, Cursor, Codex, and any MCP client can call GitHub search over stdio (nine tools, no new dependencies)
+- **Agent skill (beta)** — `ghfind skill` gives coding agents a token-efficient usage guide; `ghfind trending` accepts a language filter (`ghfind trending rust`)
+- **curl installer** — `curl -fsSL https://raw.githubusercontent.com/codersdfs/search-cli/main/scripts/install.sh | sh` downloads the standalone binary and verifies it against the release's `SHA256SUMS.txt`
+- **`NO_COLOR` support** — `ghfind --doctor` drops ANSI colors when `NO_COLOR` is set or stdout isn't a TTY
+- Fixed the stale `scripts/brew.rb` formula (wrong repo, version, and asset names)
 
-### v9.3.0
+### v9.5.1
 
-- Fixed `c` keybinding in TUI not adding repos to comparison — a missing closing brace in the space-key handler broke every later key handler (`c`, `t`, `?`)
-- README viewer renders full markdown (headings, code blocks, lists, tables, blockquotes, rules) instead of stripping formatting
-- Widened compare table columns (min 35 chars), added Description + URL rows, and raised the topic cap to 5 per repo
+- Fixed landing-screen keys leaking into the main view — `/`, `Space`, `t`, `c`, `?`, `q` all double-fired; `b` on the landing screen now opens Bookmarks
+- Fixed the update panel clipping the changelog — release notes are now scrollable (`↑↓`/`j`/`k`, `PgUp`/`PgDn`, `Home`/`End`) in a taller panel
 
 ---
 

package/completions/ghfind.bash

@@ -7,7 +7,7 @@ _ghfind() {
   cur="${COMP_WORDS[COMP_CWORD]}"
   prev="${COMP_WORDS[COMP_CWORD-1]}"
 
-  opts="--json --csv --markdown --count --limit --sort --token --trending --since --pipe --format --registry --watch --interval --version --help --completion pkg login init doctor org"
+  opts="--json --csv --markdown --count --limit --sort --token --trending --language --since --pipe --format --registry --watch --interval --version --help --completion pkg login init doctor org mcp skill trending deep-dive"
 
   case "${prev}" in
     --sort)
@@ -34,6 +34,10 @@ _ghfind() {
       COMPREPLY=( $(compgen -W "npm" -- "${cur}") )
       return 0
       ;;
+    --language)
+      COMPREPLY=( $(compgen -W "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig" -- "${cur}") )
+      return 0
+      ;;
     --limit|--interval)
       return 0
       ;;

package/completions/ghfind.fish

@@ -9,6 +9,7 @@ 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 language -d "Trending language filter" -r -f -a "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig"
 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"
@@ -20,4 +21,4 @@ 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"
 
-complete -c ghfind -f -a "login init doctor org pkg"
+complete -c ghfind -f -a "login init doctor org pkg mcp skill trending deep-dive"

package/completions/ghfind.zsh

@@ -12,6 +12,7 @@ _ghfind() {
     '--sort[Sort strategy]:(best-match stars updated forks)'
     '--token[GitHub token]:token:'
     '--trending[Trending mode]'
+    '--language[Trending language filter]:language:'
     '--since[Trending period]:(daily weekly monthly)'
     '--pipe[Pipe target]:(clone open)'
     '--format[Output format]:(urls names ssh-urls clone-commands ids)'
@@ -28,6 +29,10 @@ _ghfind() {
     'doctor[Environment diagnostics]'
     'org[Org profile]:org name:'
     'pkg[Search packages]:query:'
+    'trending[Trending repos, optionally by language]'
+    'deep-dive[Repo deep-dive: languages, contributors, README]:owner/repo:'
+    'mcp[Run the MCP server for AI agents (stdio)]'
+    'skill[Print an agent skill guide]:skill name:'
   )
   _arguments "${opts[@]}" '*:query:'
 }