github-search-cli 9.5.1 → 9.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.5.1",
+  "version": "9.7.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.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/release-notes/9.7.0.md

@@ -0,0 +1,53 @@
+# What's New in ghfind 9.7.0
+
+CLI parity with the MCP tools — everything `ghfind mcp` exposes to coding
+agents is now a first-class terminal command — plus two fixes: `ghfind mcp`
+compiles again, and deep-dive shows real repo metadata.
+
+### Added
+
+**`ghfind deep-dive <owner/repo>`** — the MCP-only deep dive, on the CLI
+
+- Language breakdown with percentages, top contributors, and a README
+  excerpt (main → master → README.rst fallback)
+- Previously the agent skill doc literally told agents to `curl` GitHub
+  instead — not anymore
+- `--json` exposes a structured payload (language percents, contributor
+  counts, raw README) suitable for agents and scripting
+- Resolves real repo metadata first: `ghfind deep-dive vercel/next.js
+--json` reports actual stars, description, topics, and timestamps
+- A 404 exits with `Repo not found: owner/name` instead of silently
+  printing empty sections; network failures still degrade gracefully
+
+**`ghfind --compare` export formats** — `--json`, `--csv`, `--markdown`
+
+- Compare was text-only ("no JSON formatter for it yet"); all three
+  formatters now exist, with columns matching the other export modes
+- Repos that fail to resolve are reported in text output and excluded from
+  the table; fewer than 2 resolvable repos exits non-zero
+
+**Trending language filter on the CLI**
+
+- `ghfind trending rust` — the form the README already advertised but the
+  parser never handled — and `ghfind --trending rust` both work now
+- `ghfind --trending --language <lang>` names the flag explicitly
+- Unknown filters are rejected with the accepted list, the same validation
+  the `ghfind_trending` MCP tool applies
+
+### Changed
+
+- The MCP server now shares its repo-ref parsing, trending-language
+  validation, and deep-dive data pipeline with the CLI (new seams in
+  `deepdive.ts` and `search.ts`) — one source of truth, no protocol
+  behavior change
+
+### Fixed
+
+- **`ghfind mcp` failed to typecheck** — the id handed to
+  `respond`/`respondError` stayed `JsonRpcId | undefined` because
+  TypeScript's aliased-conditional narrowing does not apply through a `let`
+  binding; the id is now a `const`. Runtime behavior was already correct —
+  all 31 MCP tests pass unchanged.
+- **Deep-dive ran on a zeroed repo stub** — stars, forks, description, and
+  topics were all empty in both the CLI and the `ghfind_deep_dive` MCP
+  tool; real metadata is now fetched first (see above).

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,141 @@
+/**
+ * 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] [--language rust]
+    ghfind trending rust --json      # subcommand form of the same thing
+
+## 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|--csv|--markdown]
+Errors if fewer than 2 of the requested repos resolve; unresolved names are
+reported in text output and via the error message.
+
+## Deep-dive a repo (languages, contributors, README)
+
+    ghfind deep-dive owner/repo --json
+Text output (no flag) prints the same sections formatted for the terminal.
+
+## 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");
+}