github-search-cli 9.5.0 → 9.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.5.0",
+  "version": "9.6.0",
   "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",

package/release-notes/9.5.1.md

@@ -0,0 +1,36 @@
+# What's New in ghfind 9.5.1
+
+Two TUI bugs in the landing menu and the update panel, plus test-isolation work.
+
+### Fixed
+
+**Landing-screen keys no longer leak into the main view**
+
+- Pressing `/` on the landing menu focused the search input on top of it
+- `Space`, `t`, `c`, `?`, and `q` all double-fired through the second key
+  listener — help opened and instantly closed, quit ran cleanup twice
+- The landing handler now claims its keys with `stopPropagation()` via the
+  `landingKeysActive` / `landingConsumesKey` seam, and the global handler
+  ignores everything while the landing menu owns the screen
+- Also fixed while routing keys: `b` on the landing screen opens bookmarks
+  (hint bar updated), and overlays opened from landing hide the menu instead
+  of drawing on top of it
+
+**Update panel no longer clips the changelog**
+
+- The modal was hard-capped at 16 rows with the release notes in a single
+  unsized text block, so anything past the first ~10 lines was invisible
+- The notes area is now a scrollable region (same mechanics as the
+  README/org viewers): `↑↓`/`j`/`k` move a fifth of a page,
+  `PageUp`/`PageDown` and `Home`/`End` jump, and a scrollbar appears when
+  content overflows
+- The panel is taller (24 rows), scroll position resets each time it opens,
+  and notes render at the panel's real width so wrapped lines don't clip
+  horizontally on narrow terminals
+
+### Internal
+
+- Seven test suites built temp dirs from a `Date.now()` stamp
+  (`tmpdir()/<name>-<ms>`), a name two concurrent `bun test` processes can
+  collide on. They now use `mkdtempSync`, and the login
+  `readGhCliToken` / `persistToken` dirs are cleaned up after use

package/release-notes/9.6.0.md

@@ -0,0 +1,67 @@
+# What's New in ghfind 9.6.0
+
+ghfind now speaks the Model Context Protocol — your coding agent can search
+GitHub through it — plus a curl installer and quieter output for `NO_COLOR`
+users.
+
+### Added
+
+**MCP server (beta) (`ghfind mcp`)** — ghfind as a tool server for coding agents
+
+- Any MCP client (Claude Code, Cursor, Codex, …) can call GitHub search as
+  tools over stdio; zero new dependencies, 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`, `ghfind_skill`
+- Implements the 2025-06-18 lifecycle (initialize → initialized notification →
+  operation); also speaks 2025-03-26 and 2024-11-05
+- Tool failures report as `isError` results per spec — the agent sees the
+  error, not a hang
+- Agent searches land in the TUI history like your own searches
+- `ghfind mcp --token <t>` pins a token; otherwise config / `GITHUB_TOKEN`
+  applies as usual
+
+**`ghfind skill [name]` (beta)** — a token-efficient usage guide for coding agents
+
+- Search syntax, flags, rate limits, and token-efficiency tips, so agents
+  stop guessing from `--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** — `ghfind trending` accepts a language slug
+(`rust`, `python`, …), validated against the known language list; unknown
+slugs are dropped instead of scraping an error page. Also exposed to agents
+via the `ghfind_trending` MCP tool. _(The MCP server and agent skill are
+beta — surface may still shift in 9.6.x patch releases.)_
+
+**curl installer** — no Node.js needed
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/codersdfs/search-cli/main/scripts/install.sh | sh
+```
+
+- Detects OS and arch, downloads the standalone `ghfind` binary from GitHub
+  Releases, verifies it against the release's `SHA256SUMS.txt`, and installs
+  to `~/.local/bin` (or `/usr/local/bin`, overridable with
+  `GHFIND_INSTALL_DIR`) — never needs sudo, prints a PATH hint if needed
+- Every release now ships a merged `SHA256SUMS.txt` alongside the binaries,
+  so package maintainers can verify the same way
+
+**`NO_COLOR` support** — `ghfind --doctor` stops emitting ANSI color codes
+when `NO_COLOR` is set (any value, per no-color.org) or when stdout is not a
+TTY. Piping `--doctor` into a file or CI log no longer drags escape codes
+along.
+
+### Fixed
+
+- **`scripts/brew.rb` 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-*` names (plus linux-arm64), a livecheck
+  block, and a version-pinning test.
+- **Community health files** — `SECURITY.md` (private vulnerability
+  reporting), `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1), and
+  `SUPPORT.md` (routes you to `--doctor` first) now exist, so security
+  reports and "it doesn't work" issues have proper homes.

package/scripts/brew.rb

@@ -1,32 +1,53 @@
 # typed: true
 # frozen_string_literal: true
 
-class SearchCli < Formula
-  desc "Interactive GitHub repository browser for the terminal"
-  homepage "https://github.com/frank/search-cli"
-  version "0.1.0"
+# Homebrew formula for ghfind.
+#
+# NOTE: this file is a template, kept in-tree for a future homebrew tap.
+# Before use:
+#   1. Replace VERSION with the released version tag.
+#   2. Fill SHA256 placeholders from the SHA256SUMS.txt asset attached to
+#      the GitHub Release (the release workflow generates it).
+#   3. Host it in a tap repo (e.g. codersdfs/tap) at Formula/ghfind.rb,
+#      then: brew install codersdfs/tap/ghfind
+# See marketing/README.md (Track B) for the rollout order.
+
+class Ghfind < Formula
+  desc "Search GitHub repos from your terminal — trending, bookmarks, deep-dive"
+  homepage "https://github.com/codersdfs/search-cli"
+  version "9.5.1"
   license "MIT"
 
+  livecheck do
+    url :stable
+    regex(/^v?(\d+(?:\.\d+)+)$/i)
+  end
+
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/frank/search-cli/releases/download/v#{version}/search-cli-darwin-arm64"
+      url "https://github.com/codersdfs/search-cli/releases/download/v#{version}/ghfind-darwin-arm64"
       sha256 "SHA256_PLACEHOLDER"
     else
-      url "https://github.com/frank/search-cli/releases/download/v#{version}/search-cli-darwin-x64"
+      url "https://github.com/codersdfs/search-cli/releases/download/v#{version}/ghfind-darwin-x64"
       sha256 "SHA256_PLACEHOLDER"
     end
   end
 
   on_linux do
-    url "https://github.com/frank/search-cli/releases/download/v#{version}/search-cli-linux-x64"
-    sha256 "SHA256_PLACEHOLDER"
+    if Hardware::CPU.arm? && Hardware::CPU.is_64_bit?
+      url "https://github.com/codersdfs/search-cli/releases/download/v#{version}/ghfind-linux-arm64"
+      sha256 "SHA256_PLACEHOLDER"
+    else
+      url "https://github.com/codersdfs/search-cli/releases/download/v#{version}/ghfind-linux-x64"
+      sha256 "SHA256_PLACEHOLDER"
+    end
   end
 
   def install
-    bin.install "search-cli"
+    bin.install "ghfind" => "ghfind"
   end
 
   test do
-    assert_match "search-cli", shell_output("#{bin}/search-cli --version")
+    assert_match version.to_s, shell_output("#{bin}/ghfind --version")
   end
 end

package/scripts/install.sh

@@ -0,0 +1,118 @@
+#!/bin/sh
+# ghfind installer — https://github.com/codersdfs/search-cli
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/codersdfs/search-cli/main/scripts/install.sh | sh
+#
+# Downloads the standalone ghfind binary for your platform from GitHub
+# Releases (no Node.js or Bun needed) into ~/.local/bin, /usr/local/bin,
+# or a directory of your choice via GHFIND_INSTALL_DIR.
+#
+# Options via environment:
+#   GHFIND_VERSION   a release tag without the leading v (default: latest)
+#   GHFIND_INSTALL_DIR  target dir (default: ~/.local/bin if writable)
+#
+# The script never needs sudo: if the default dir is not writable it falls
+# back to ~/.local/bin and prints a PATH reminder.
+
+set -eu
+
+REPO="codersdfs/search-cli"
+
+printf '\n' # cosmetic spacing when piped
+
+# ── Detect platform ────────────────────────────────────────────────────
+os=$(uname -s)
+arch=$(uname -m)
+
+case "$os" in
+  Linux) plat="linux" ;;
+  Darwin) plat="darwin" ;;
+  *)
+    printf 'ghfind install: unsupported OS "%s".\n' "$os"
+    printf 'Windows: install with npm (npm i -g github-search-cli) or scoop/winget once listed.\n' >&2
+    exit 1
+    ;;
+esac
+
+case "$arch" in
+  x86_64 | amd64) arch="x64" ;;
+  aarch64 | arm64) arch="arm64" ;;
+  *)
+    printf 'ghfind install: unsupported architecture "%s".\n' "$arch" >&2
+    exit 1
+    ;;
+esac
+
+asset="ghfind-${plat}-${arch}"
+
+# ── Resolve version ────────────────────────────────────────────────────
+if [ -n "${GHFIND_VERSION:-}" ]; then
+  version="$GHFIND_VERSION"
+else
+  # Latest release tag, following redirects; avoids a jq dependency.
+  version=$(curl -fsSLI -o /dev/null -w '%{url_effective}' \
+    "https://github.com/${REPO}/releases/latest" | sed 's|.*/tag/v||')
+  if [ -z "$version" ] || [ "$version" = "latest" ]; then
+    printf 'ghfind install: could not resolve the latest release version.\n' >&2
+    exit 1
+  fi
+fi
+
+base_url="https://github.com/${REPO}/releases/download/v${version}"
+
+# ── Pick install dir (never requires sudo) ─────────────────────────────
+if [ -n "${GHFIND_INSTALL_DIR:-}" ]; then
+  install_dir="$GHFIND_INSTALL_DIR"
+elif [ -w /usr/local/bin ] 2>/dev/null; then
+  install_dir="/usr/local/bin"
+else
+  install_dir="${HOME}/.local/bin"
+fi
+
+mkdir -p "$install_dir"
+
+# ── Download binary + checksum ─────────────────────────────────────────
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+printf 'Installing ghfind %s (%s) -> %s\n' "$version" "$asset" "$install_dir"
+
+curl -fsSL --retry 3 -o "$tmp/ghfind" "${base_url}/${asset}"
+curl -fsSL --retry 3 -o "$tmp/SHA256SUMS.txt" "${base_url}/SHA256SUMS.txt" ||
+  printf 'warning: could not download SHA256SUMS.txt; skipping checksum verification\n'
+
+# ── Verify checksum when we have the sums file ─────────────────────────
+if [ -f "$tmp/SHA256SUMS.txt" ]; then
+  expected=$(grep " ${asset}\$" "$tmp/SHA256SUMS.txt" | awk '{print $1}')
+  if [ -n "$expected" ]; then
+    if command -v sha256sum >/dev/null 2>&1; then
+      actual=$(sha256sum "$tmp/ghfind" | awk '{print $1}')
+    elif command -v shasum >/dev/null 2>&1; then
+      actual=$(shasum -a 256 "$tmp/ghfind" | awk '{print $1}')
+    else
+      actual=""
+      printf 'warning: no sha256sum/shasum found; skipping checksum verification\n'
+    fi
+    if [ -n "$actual" ] && [ "$actual" != "$expected" ]; then
+      printf 'ghfind install: checksum mismatch!\n  expected %s\n  actual   %s\n' "$expected" "$actual" >&2
+      exit 1
+    fi
+    [ -n "$actual" ] && printf 'Checksum OK (%s)\n' "$actual"
+  fi
+fi
+
+# ── Install ────────────────────────────────────────────────────────────
+mv "$tmp/ghfind" "${install_dir}/ghfind"
+chmod +x "${install_dir}/ghfind"
+
+# ── PATH hint ──────────────────────────────────────────────────────────
+case ":$PATH:" in
+  *":${install_dir}:"*) ;;
+  *)
+    printf '\nNOTE: %s is not in your PATH.\n' "$install_dir"
+    printf 'Add it, e.g.:\n  echo '"'"'export PATH="%s:$PATH"'"'"' >> ~/.bashrc   # or ~/.zshrc\n' "$install_dir"
+    ;;
+esac
+
+printf 'Done. Run:  ghfind --version\n'

package/src/agent-skill.ts

@@ -0,0 +1,140 @@
+/**
+ * agent-skill.ts — `ghfind skill`: a compact, token-efficient usage guide for
+ * AI coding agents, and the module that owns the skill registry.
+ *
+ * Coding agents (Claude Code, Cursor, Codex, ...) burn tokens reading
+ * `--help` output, most of which explains the interactive TUI they cannot
+ * drive. `ghfind skill` prints a distilled, agent-shaped guide covering only
+ * the non-interactive surface, so an agent gets everything it needs in ~2 KB.
+ *
+ * The registry is deliberately generic: the built-in ghfind skill is the
+ * seed, and third parties can register their own skills alongside it
+ * (`registerSkill`) — the foundation of ghfind-as-an-agent-ecosystem.
+ */
+import { getVersion } from "./version";
+
+/** One invocable skill in the registry. */
+export interface Skill {
+  /** Unique id, e.g. "ghfind-cli". Also the `ghfind skill <id>` selector. */
+  name: string;
+  /** Human-readable display name. */
+  title: string;
+  /** When the agent should reach for this skill. */
+  description: string;
+  /** The full skill body, printed to stdout by `ghfind skill <name>`. */
+  content: string;
+  /** Registrations that are not the built-in ghfind skill. */
+  builtin?: boolean;
+}
+
+/** Build the built-in ghfind CLI skill. A function so the version is read lazily. */
+function buildGhfindSkill(): Skill {
+  return {
+    name: "ghfind-cli",
+    title: "ghfind CLI for agents",
+    description:
+      "Search GitHub (repos, trending, npm packages, org/user profiles) from the terminal via the `ghfind` command. Use when the user asks to find, compare, or track GitHub repositories or npm packages.",
+    builtin: true,
+    content: `# ghfind — GitHub search for agents
+
+ghfind searches GitHub from the terminal: repositories, trending, npm
+packages, org/user profiles. This guide covers the non-interactive surface
+only — ignore anything about a TUI in other docs; agents cannot drive it.
+
+## Search GitHub repositories
+
+    ghfind "QUERY" --json [--limit N] [--sort best-match|stars|updated|forks]
+
+Query language (GitHub search qualifiers):
+  language:Rust stars:>1000 topic:cli org:vercel user:torvalds
+  repo:facebook/react pushed:>2026-01-01 license:mit archived:false
+  "exact phrase" -language:JavaScript        # quotes, negation
+
+Formats: --json | --csv | --markdown | --count | --format urls|names|ssh-urls|clone-commands|ids
+
+## Trending repositories
+
+    ghfind --trending --json [--since daily|weekly|monthly]
+
+## npm packages
+
+    ghfind pkg "QUERY" --json [--limit N] [--sort best-match|score|downloads|name]
+
+## Org & user profiles
+
+    ghfind org vercel --json
+    ghfind user torvalds --json
+
+## Compare repositories
+
+    ghfind --compare owner/a owner/b [--json]
+Compare is text-only; there is no JSON formatter for it yet.
+
+## Deep-dive a repo (languages, contributors, README)
+
+Not exposed on the CLI. Fetch directly instead:
+  curl -s https://api.github.com/repos/OWNER/REPO/languages
+  curl -s https://raw.githubusercontent.com/OWNER/REPO/main/README.md
+
+## Rate limits
+
+60 req/hr unauthenticated, 5,000 with GITHUB_TOKEN (env var or \`ghfind login\`).
+Responses are cached ~5 min, so repeated identical queries are cheap.
+
+## Bookmarking & release tracking
+
+Bookmarks live in ghfind's local state, not GitHub. An agent can read the
+release feed with:
+    ghfind --releases --json
+Marking releases seen and editing bookmarks is a TUI action; skip it.
+
+## Token efficiency
+
+Prefer --count when only the number of results matters, --format names when
+you only need fullNames, and --limit to cap payload size (default 50, max 100).
+`,
+  };
+}
+
+// ─── Registry ───────────────────────────────────────────────────────────
+
+const registry = new Map<string, Skill>();
+
+/** Register a skill. Overwrites an existing skill with the same name. */
+export function registerSkill(skill: Skill): void {
+  registry.set(skill.name, skill);
+}
+
+/** Get a skill by name, or undefined. */
+export function getSkill(name: string): Skill | undefined {
+  return registry.get(name);
+}
+
+/** All registered skills, built-ins first, then alphabetical. */
+export function listSkills(): Skill[] {
+  return [...registry.values()].sort((a, b) => {
+    if (a.builtin !== b.builtin) return a.builtin ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+/** Load the built-in ghfind skill into the registry (idempotent). */
+export function ensureBuiltinSkill(): void {
+  if (!registry.has("ghfind-cli")) {
+    registerSkill(buildGhfindSkill());
+  }
+}
+
+/** Print the skill catalog (one line per skill) for `ghfind skill` with no id. */
+export function formatSkillCatalog(): string {
+  ensureBuiltinSkill();
+  const lines = listSkills().map(
+    (s) => `  ${s.name.padEnd(16)} ${s.description}`,
+  );
+  return [
+    "Available agent skills:",
+    ...lines,
+    "",
+    `Run \`ghfind skill <name>\` to print one (ghfind v${getVersion()}).`,
+  ].join("\n");
+}

package/src/cli.ts

@@ -53,6 +53,13 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { launchBrowser } from "./tui";
 import { getVersion } from "./version";
+import { runMcpServer } from "./mcp-server";
+import {
+  ensureBuiltinSkill,
+  formatSkillCatalog,
+  getSkill,
+  listSkills,
+} from "./agent-skill";
 import type { SearchOptions } from "./types";
 import { SearchCliError } from "./errors";
 
@@ -87,6 +94,8 @@ interface CLIFlags {
   doctor: boolean;
   org?: string; // org profile lookup (ghfind org <name>)
   user?: string; // user profile lookup (ghfind user <name>)
+  mcp: boolean; // run the MCP server (ghfind mcp)
+  skill?: string; // agent skill guide (ghfind skill [name])
 }
 
 function parseArgs(args: string[]): CLIFlags {
@@ -112,6 +121,7 @@ function parseArgs(args: string[]): CLIFlags {
     registry: "npm",
     compare: [],
     doctor: false,
+    mcp: false,
   };
 
   let queryParts: string[] = [];
@@ -191,6 +201,20 @@ function parseArgs(args: string[]): CLIFlags {
       case "--completion":
         flags.completion = args[++i];
         break;
+      case "mcp":
+        flags.mcp = true;
+        break;
+      case "skill": {
+        // Optional skill id (ids contain no spaces); a following flag means none.
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.skill = next;
+          i++;
+        } else {
+          flags.skill = "";
+        }
+        break;
+      }
       case "org": {
         // Collect org name until next flag (single token — GitHub org logins
         // contain no spaces; a quoted multi-word name is an error)
@@ -261,12 +285,13 @@ Usage:
   ghfind <query> --pipe <target>   Pipe to clone/open
   ghfind --trending --json         Trending repos as JSON
   ghfind --releases                Check bookmarks for new releases
-  ghfind --compare <repo1> <repo2> Compare two+ repos side-by-side
+  ghfind --compare <r1> <r2>       Compare two+ repos side-by-side
   ghfind org <name> --json         Org profile: repos, stars, top languages
   ghfind user <name> --json        User profile: repos, stars, top languages
-  ghfind user <name> --json        User profile: repos, stars, top languages
-  ghfind pkg <query> --json         Search npm packages, output JSON
-  ghfind pkg <query>                Search npm packages, text list
+  ghfind pkg <query> --json        Search npm packages, output JSON
+  ghfind pkg <query>               Search npm packages, text list
+  ghfind mcp                       Run the MCP server for AI agents (stdio)
+  ghfind skill [name]              Print the agent skill guide (or catalog)
   ghfind --watch <query>           Watch mode (poll every Ns)
   ghfind init                      Run setup wizard
   ghfind login                     Import the gh CLI token or paste one
@@ -321,6 +346,18 @@ Options:
     await runLoginWizard();
     return;
   }
+
+  // MCP server — expose ghfind as tools to AI agents over stdio
+  if (flags.mcp) {
+    await runMcpServer({ token: flags.token });
+    return;
+  }
+
+  // Agent skill guide — token-efficient usage doc for coding agents
+  if (flags.skill !== undefined) {
+    printAgentSkill(flags.skill);
+    return;
+  }
   // Package search (prototype, ticket 002-008)
   if (flags.pkg) {
     const interactive =
@@ -396,6 +433,25 @@ function buildSearchContext(flags: CLIFlags): SearchContext {
   };
 }
 
+/** `ghfind skill [name]` — print the agent skill catalog or one skill's content. */
+function printAgentSkill(name: string): void {
+  ensureBuiltinSkill();
+  if (!name) {
+    console.log(formatSkillCatalog());
+    return;
+  }
+  const skill = getSkill(name);
+  if (!skill) {
+    console.error(
+      `Unknown skill: ${name}. Available: ${listSkills()
+        .map((s) => s.name)
+        .join(", ")}`,
+    );
+    process.exit(1);
+  }
+  console.log(skill.content);
+}
+
 /** `ghfind user <name>` — aggregate user profile: metadata, stars, top languages, top repos. */
 async function runUserProfile(
   flags: CLIFlags,

package/src/doctor.ts

@@ -237,7 +237,11 @@ function checkDirs(): void {
 }
 
 function printReport(): void {
+  // Respect NO_COLOR (https://no-color.org/): plain text when set (any value,
+  // including the empty string) or when stdout is not a TTY.
+  const noColor = process.env.NO_COLOR !== undefined || !process.stdout.isTTY;
   const colors = (s: string, n: CheckStatus) => {
+    if (noColor) return s;
     const code =
       n === "PASS" ? "\x1b[32m" : n === "WARN" ? "\x1b[33m" : "\x1b[31m";
     return `${code}${s}\x1b[0m`;

package/src/help.ts

@@ -82,6 +82,10 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "Packages", action: "Switch to npm packages" },
         { keys: "Export", action: "Export results to file" },
         { keys: "Share", action: "Share repo as text" },
+        {
+          keys: "Org profile",
+          action: "Org summary: repos, stars, top languages",
+        },
         { keys: "Topics", action: "Browse GitHub topics" },
         { keys: "Saved", action: "View saved searches" },
         { keys: "Notifs", action: "Check GitHub notifications" },