github-search-cli 9.5.0 → 9.6.0

package/CHANGELOG.md

@@ -6,7 +6,60 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
-## [Unreleased]
+## [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
 
@@ -20,7 +73,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
   screen. Also fixed while routing keys: `b` on the landing screen now opens
   bookmarks (hint bar updated), and overlays opened from landing hide the
   menu instead of drawing on top of it.
-
 - **Update panel clipped the changelog** — the modal was hard-capped at 16
   rows and put the release notes in a single unsized text block, so anything
   past the first ~10 lines of the notes was invisible with no hint that more
@@ -30,10 +82,40 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
   position resets each time the panel opens. The box is taller (24 rows), and
   notes render at the panel's actual width so wrapped lines no longer clip
   horizontally on narrow terminals.
+- **`--help` listed `ghfind user <name>` twice** — the 9.5.0 usage block
+  carried a duplicated line, so the profile examples were printed twice. It
+  now appears once, and the `ghfind pkg` line is aligned with its neighbours.
+
+### Internal
+
+- **Test isolation** — seven suites derived their temp dirs from a
+  `Date.now()` stamp (`tmpdir()/<name>-<ms>`), a name two concurrent
+  `bun test` processes can collide on, which intermittently failed
+  bookmarks / config / doctor / history / login / saved-searches /
+  update-check tests. They now use `mkdtempSync`, which is unique and
+  collision-proof (the pattern `tests/releases.test.ts` already used), and
+  the login `readGhCliToken` / `persistToken` dirs are removed after use
+  instead of accumulating in the temp folder.
+- **Docs sync** (README ↔ `src/help.ts` ↔ `--help`): README gained
+  `--releases` / `--compare` / `pkg` examples plus Packages and Releases
+  feature rows; the TUI help screen gained the `Org profile` command-menu
+  entry the leader menu already had. `tests/cli-help.test.ts` pins the
+  `--help` usage block (no duplicate rows, one description column).
+- `package-lock.json` root version synced to 9.5.1 (`bun.lock` carries no
+  root version), and the release workflow's manual dispatch now runs the
+  gate only — the GitHub Release and npm publish jobs are tag-gated, so
+  dispatching from a branch can't create a release on a non-tag ref.
+- `--doctor` tests remove their temp config dirs after each test instead of
+  leaving them behind.
+- **CI was red on `windows-latest`** — `tests/landing.test.ts` source-greps
+  `src/tui.ts` for a snippet containing `\n`, but Windows checks the tree out
+  with CRLF, so the assertion could never match there while every other OS
+  passed. The source-grep helpers now normalise line endings before
+  asserting; `tests/overlay-registry.test.ts` does the same.
 
 ---
 
-## [9.5.0] — 2026-09-15
+## [9.5.0] — 2026-09-15 (released)
 
 ### Added
 

package/README.md

@@ -26,6 +26,14 @@
 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?
@@ -81,6 +89,43 @@ 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
+ghfind --releases            # new releases for bookmarked repos
+ghfind --compare a/b c/d     # side-by-side comparison
+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
@@ -98,6 +143,7 @@ ghfind --completion fish | source
 <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>Packages</b></td><td>npm registry search (beta) — <code>ghfind pkg "query"</code></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>
@@ -109,9 +155,12 @@ ghfind --completion fish | source
 <tr><td><b>Org profile</b></td><td>Space → Org profile — org summary: repos, stars, top languages (<code>ghfind org <name></code> in CLI)</td></tr>
 <tr><td><b>User profile</b></td><td>User summary like org profile — repos, stars, followers, top languages (<code>ghfind user <name></code>)</td></tr>
 <tr><td><b>Notifications</b></td><td>Space → Notifications — view & dismiss alerts</td></tr>
+<tr><td><b>Releases</b></td><td><code>--releases</code> — new-release feed for bookmarked repos</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>
+<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>
@@ -219,7 +268,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/))
 
 ---
 
@@ -232,14 +281,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 292 tests
+bun test         # 335 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         # 292 tests
+npm test         # 335 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -252,39 +301,24 @@ npm run build    # build dist/
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
-### v9.5.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
-- 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
-
-### v9.3.0
-
-- 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
-
-### v9.2.1
+### v9.6.0
 
-- npm package search (beta) and a new landing screen
-- Removed the bundled Bun binary — downloaded at install time instead; package size 39.5 MB → 100 KB
-- Postinstall failures no longer break `npm install`; `bun` dropped from engines
-- Fixed TUI layout on small terminals, trending visibility from the landing screen, and independent trending-tab fetches
+- **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.1.1
+### v9.5.1
 
-- Bundle `vendor/` and `dist/` for offline install
-- Postinstall exits non-zero on Bun download failure; bundled Bun 1.3.12 → 1.3.14
+- 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
 
-### v9.1.0
+### v9.5.0
 
-- Automatic update checking against the npm registry, with a Y/N/L modal
-- Leader menu (Space) consolidating all contextual actions
-- Topic explorer, notifications panel, saved searches, activity graph, README viewer
-- Tab qualifier auto-complete, PageUp/PageDown, `Ctrl+X` clear history, `Ctrl+C` clear notifications
-- TUI runs on Node.js 20+ via the downloaded Bun binary
+- 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
 
 ---
 

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 --since --pipe --format --registry --watch --interval --version --help --completion pkg login init doctor org mcp skill"
 
   case "${prev}" in
     --sort)

package/completions/ghfind.fish

@@ -20,4 +20,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"

package/completions/ghfind.zsh

@@ -28,6 +28,8 @@ _ghfind() {
     'doctor[Environment diagnostics]'
     'org[Org profile]:org name:'
     'pkg[Search packages]:query:'
+    'mcp[Run the MCP server for AI agents (stdio)]'
+    'skill[Print an agent skill guide]:skill name:'
   )
   _arguments "${opts[@]}" '*:query:'
 }