github-search-cli 9.6.0 → 9.7.0

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/src/agent-skill.ts

@@ -54,7 +54,8 @@ Formats: --json | --csv | --markdown | --count | --format urls|names|ssh-urls|cl
 
 ## Trending repositories
 
-    ghfind --trending --json [--since daily|weekly|monthly]
+    ghfind --trending --json [--since daily|weekly|monthly] [--language rust]
+    ghfind trending rust --json      # subcommand form of the same thing
 
 ## npm packages
 
@@ -67,14 +68,14 @@ Formats: --json | --csv | --markdown | --count | --format urls|names|ssh-urls|cl
 
 ## Compare repositories
 
-    ghfind --compare owner/a owner/b [--json]
-Compare is text-only; there is no JSON formatter for it yet.
+    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)
 
-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
+    ghfind deep-dive owner/repo --json
+Text output (no flag) prints the same sections formatted for the terminal.
 
 ## Rate limits
 

package/src/cli.ts

@@ -46,7 +46,20 @@ import {
 import { checkAndNotify, allCachedReleases } from "./releases";
 import { runInitWizard } from "./init";
 import { runLoginWizard } from "./login";
-import { buildComparisonTable } from "./compare";
+import {
+  buildComparisonTable,
+  comparisonJson,
+  comparisonCsv,
+  comparisonMarkdown,
+} from "./compare";
+import {
+  fetchDeepDiveRaw,
+  buildDeepDiveData,
+  buildDeepDiveJson,
+  buildDeepDiveText,
+  resolveRepoFromRef,
+} from "./deepdive";
+import { resolveTrendingLanguage } from "./search";
 import type { Repo } from "./types";
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
@@ -96,6 +109,8 @@ interface CLIFlags {
   user?: string; // user profile lookup (ghfind user <name>)
   mcp: boolean; // run the MCP server (ghfind mcp)
   skill?: string; // agent skill guide (ghfind skill [name])
+  deepDive?: string; // repo deep-dive (ghfind deep-dive <owner/repo>)
+  language?: string; // trending language filter (--trending rust / ghfind trending rust)
 }
 
 function parseArgs(args: string[]): CLIFlags {
@@ -142,6 +157,23 @@ function parseArgs(args: string[]): CLIFlags {
         break;
       case "--trending":
         flags.trending = true;
+        // `ghfind --trending rust` — first bare word is the language filter
+        break;
+      case "trending": {
+        // `ghfind trending rust` — subcommand form of --trending (README has
+        // claimed this works; now it does).
+        flags.trending = true;
+        if (
+          flags.query === "" &&
+          i + 1 < args.length &&
+          !args[i + 1].startsWith("-")
+        ) {
+          flags.language = args[++i];
+        }
+        break;
+      }
+      case "--language":
+        flags.language = args[++i];
         break;
       case "--watch":
         flags.watch = true;
@@ -204,6 +236,15 @@ function parseArgs(args: string[]): CLIFlags {
       case "mcp":
         flags.mcp = true;
         break;
+      case "deep-dive": {
+        // Single repo ref (owner/name); a following flag means none.
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.deepDive = next;
+          i++;
+        }
+        break;
+      }
       case "skill": {
         // Optional skill id (ids contain no spaces); a following flag means none.
         const next = args[i + 1];
@@ -284,8 +325,12 @@ Usage:
   ghfind <query> --format <fmt>    Format lines (urls|names|ssh-urls|clone-commands|ids)
   ghfind <query> --pipe <target>   Pipe to clone/open
   ghfind --trending --json         Trending repos as JSON
+  ghfind trending <lang>           Trending repos, optionally by language
   ghfind --releases                Check bookmarks for new releases
   ghfind --compare <r1> <r2>       Compare two+ repos side-by-side
+  ghfind --compare a/b c/d --json  Compare as JSON|CSV|Markdown
+  ghfind deep-dive <owner/repo>    Deep-dive: languages, contributors, README
+  ghfind deep-dive a/b --json      Deep-dive as JSON
   ghfind org <name> --json         Org profile: repos, stars, top languages
   ghfind user <name> --json        User profile: repos, stars, top languages
   ghfind pkg <query> --json        Search npm packages, output JSON
@@ -306,6 +351,7 @@ Options:
   --sort <strategy>                    Sort: best-match|stars|updated|forks
   --theme <name>                     Theme: tokyo-night|premium-dark (default: tokyo-night)
   --trending                           Trending mode
+  --language <lang>                    Trending language filter (e.g. rust)
   --since <period>                     Trending period: daily|weekly|monthly
   --pipe <target>                      Pipe target: clone|open
   --format <fmt>                       Line format: urls|names|ssh-urls|...
@@ -384,6 +430,12 @@ Options:
         ? "markdown"
         : undefined;
 
+  // Repo deep-dive — parity with the MCP ghfind_deep_dive tool
+  if (flags.deepDive !== undefined) {
+    await runDeepDive(flags, outputFormat);
+    return;
+  }
+
   // Org profile mode — independent of repo search handlers
   // (checks presence, not truthiness, so `ghfind org` with no name errors helpfully)
   if (flags.org !== undefined) {
@@ -403,7 +455,10 @@ Options:
     flags.format ||
     flags.pipe ||
     flags.watch ||
-    flags.releases;
+    flags.releases ||
+    // `ghfind trending rust` / `ghfind --trending rust` print a list —
+    // a language filter implies non-interactive output
+    (flags.trending && (!!flags.language || !!flags.query));
 
   // Non-interactive mode
   if (isNonInteractive) {
@@ -506,6 +561,32 @@ async function runOrgProfile(
   }
 }
 
+/** `ghfind deep-dive <owner/repo>` — rich repo detail: languages, contributors, README. */
+async function runDeepDive(
+  flags: CLIFlags,
+  outputFormat?: ExportFormat,
+): Promise<void> {
+  const ref = flags.deepDive!;
+  if (!ref) {
+    console.error(
+      "Usage: ghfind deep-dive <owner/repo> [--json] [--token <t>]",
+    );
+    process.exit(1);
+  }
+  try {
+    const repo = await resolveRepoFromRef(ref, flags.token); // validates + real metadata
+    const raw = await fetchDeepDiveRaw(repo, flags.token);
+    if (outputFormat === "json") {
+      console.log(buildDeepDiveJson(raw));
+    } else {
+      console.log(buildDeepDiveText(buildDeepDiveData(repo, raw)));
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
 /** `ghfind pkg "<query>"` — npm package search. Pass-through query to the registry. */
 async function runPackageSearch(flags: CLIFlags): Promise<void> {
   if (flags.registry !== "npm") {
@@ -611,6 +692,20 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
             ? "monthly"
             : "daily";
       const trendingSearch = createTrendingSearch();
+      // Language filter: validated against github.com/trending's accepted
+      // set (same validation as the MCP ghfind_trending tool).
+      let language: string | undefined;
+      try {
+        // `ghfind trending rust` puts the language in flags.language;
+        // `ghfind --trending rust` leaves it as the query's first word.
+        language = resolveTrendingLanguage(
+          flags.language ??
+            (flags.query ? flags.query.split(/\s+/)[0] : undefined),
+        );
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
       const response = await trendingSearch.search(
         { keywords: [], qualifiers: [], raw: "trending" },
         {
@@ -619,6 +714,7 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
           json: false,
           verbose: false,
           trendingSince: since,
+          ...(language ? { trendingLanguage: language } : {}),
         },
       );
       if (outputFormat) {
@@ -710,6 +806,7 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
     compare: async (_ctx) => {
       const search = createGitHubSearch(undefined, [flags.token ?? ""]);
       const repos: Repo[] = [];
+      const missing: string[] = [];
       for (const fullName of flags.compare) {
         const res = await search.search(
           { keywords: [fullName], qualifiers: [], raw: fullName },
@@ -721,9 +818,27 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
             token: flags.token,
           },
         );
-        repos.push(...res.repos);
+        if (res.repos.length > 0) repos.push(...res.repos);
+        else missing.push(fullName);
+      }
+      if (repos.length < 2) {
+        console.error(
+          `Could not resolve enough repos to compare (found ${repos.length}${missing.length ? `; not found: ${missing.join(", ")}` : ""}).`,
+        );
+        process.exit(1);
+      }
+      const notFound = missing.length
+        ? `\n\nNot found: ${missing.join(", ")}`
+        : "";
+      if (outputFormat === "json") {
+        console.log(comparisonJson(repos));
+      } else if (outputFormat === "csv") {
+        console.log(comparisonCsv(repos));
+      } else if (outputFormat === "markdown") {
+        console.log(comparisonMarkdown(repos));
+      } else {
+        console.log(buildComparisonTable(repos) + notFound);
       }
-      console.log(buildComparisonTable(repos));
     },
   };
 

package/src/compare.ts

@@ -1,5 +1,6 @@
 /**
- * Repo comparison — side-by-side table for 2+ repos.
+ * Repo comparison — side-by-side table for 2+ repos, plus JSON/CSV/Markdown
+ * exports (shared by the CLI `--compare` formatters and the MCP server).
  */
 import type { Repo } from "./types";
 
@@ -67,3 +68,77 @@ export function buildComparisonTable(repos: Repo[]): string {
   lines.push("└" + sep.map((s) => "─" + s + "─").join("┴") + "┘");
   return lines.join("\n");
 }
+
+// ─── Export formatters (parity with org/user/package modules) ──────────
+
+/** The repo fields the comparison surface exposes. */
+export interface ComparisonRepo {
+  fullName: string;
+  url: string;
+  description: string | null;
+  stars: number;
+  forks: number;
+  language: string | null;
+  createdAt: string;
+  updatedAt: string;
+  topics: string[];
+  archived: boolean;
+}
+
+function comparisonRepo(r: Repo): ComparisonRepo {
+  return {
+    fullName: r.fullName,
+    url: r.url,
+    description: r.description,
+    stars: r.stars,
+    forks: r.forks,
+    language: r.language,
+    createdAt: r.createdAt,
+    updatedAt: r.updatedAt,
+    topics: r.topics,
+    archived: r.archived,
+  };
+}
+
+export function comparisonJson(repos: Repo[]): string {
+  return JSON.stringify(repos.map(comparisonRepo), null, 2);
+}
+
+function csvEscape(val: unknown): string {
+  const str = String(val ?? "");
+  if (str.includes('"') || str.includes(",") || str.includes("\n")) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+export function comparisonCsv(repos: Repo[]): string {
+  const header = "full_name,stars,forks,language,created,updated,archived,url";
+  const rows = repos.map((r) =>
+    [
+      r.fullName,
+      r.stars,
+      r.forks,
+      r.language ?? "",
+      r.createdAt?.slice(0, 10) ?? "",
+      r.updatedAt?.slice(0, 10) ?? "",
+      String(r.archived),
+      r.url,
+    ]
+      .map(csvEscape)
+      .join(","),
+  );
+  return [header, ...rows].join("\n");
+}
+
+export function comparisonMarkdown(repos: Repo[]): string {
+  const header =
+    "| Repo | Stars | Forks | Language | Created | Updated | Topics |";
+  const sep =
+    "|------|-------|-------|----------|---------|---------|--------|";
+  const rows = repos.map(
+    (r) =>
+      `| [${r.fullName}](${r.url}) | ${r.stars.toLocaleString()} | ${r.forks.toLocaleString()} | ${r.language ?? "—"} | ${r.createdAt?.slice(0, 7) ?? "—"} | ${r.updatedAt?.slice(0, 10) ?? "—"} | ${(r.topics?.slice(0, 5).join(", ") ?? "") || "—"} |`,
+  );
+  return [header, sep, ...rows].join("\n");
+}

package/src/deepdive.ts

@@ -10,6 +10,119 @@ function buildHeaders(token?: string): Record<string, string> {
   return headers;
 }
 
+// ─── Repo ref parsing (shared by the CLI deep-dive and the MCP server) ─
+
+const REPO_REF_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/**
+ * Parse a repo reference ("owner/name") into its parts. Tolerates a trailing
+ * `.git` and a leading `@`. Throws with a user-facing message for anything else.
+ */
+export function parseRepoRef(input: string): { owner: string; name: string } {
+  const fullName = input
+    .trim()
+    .replace(/\.git$/, "")
+    .replace(/^@/, "");
+  if (!REPO_REF_RE.test(fullName)) {
+    throw new Error(
+      `"${input}" is not a repo name — use owner/name, e.g. facebook/react.`,
+    );
+  }
+  const [owner, name] = fullName.split("/");
+  return { owner, name };
+}
+
+/** Minimal Repo for deep-dive (the fetchers only read owner/name). */
+export function repoFromRef(fullName: string): Repo {
+  const { owner, name } = parseRepoRef(fullName);
+  return {
+    id: 0,
+    fullName: `${owner}/${name}`,
+    name,
+    owner,
+    description: null,
+    url: `https://github.com/${owner}/${name}`,
+    stars: 0,
+    forks: 0,
+    watchers: 0,
+    language: null,
+    topics: [],
+    archived: false,
+    isFork: false,
+    private: false,
+    createdAt: "",
+    updatedAt: "",
+    pushedAt: "",
+    score: 0,
+  };
+}
+
+/**
+ * Resolve a repo ref to a real Repo by fetching canonical metadata from the
+ * GitHub API. Returns a stub via repoFromRef when the metadata fetch fails
+ * (offline, rate limit) — the ref is still validated first. Deep-dive
+ * sub-fetches tolerate missing data either way.
+ */
+export async function resolveRepoFromRef(
+  fullName: string,
+  token?: string,
+): Promise<Repo> {
+  const ref = parseRepoRef(fullName); // throws for malformed refs
+  const canonical = `${ref.owner}/${ref.name}`;
+  try {
+    const res = await fetch(`https://api.github.com/repos/${canonical}`, {
+      headers: buildHeaders(token),
+    });
+    if (res.status === 404) {
+      throw new Error(`Repo not found: ${canonical}`);
+    }
+    if (res.ok) {
+      const api = (await res.json()) as {
+        description: string | null;
+        html_url: string;
+        stargazers_count: number;
+        forks_count: number;
+        subscribers_count?: number;
+        language: string | null;
+        topics?: string[];
+        archived: boolean;
+        fork: boolean;
+        created_at: string;
+        updated_at: string;
+        pushed_at: string;
+      };
+      return {
+        id: 0,
+        fullName: canonical,
+        name: ref.name,
+        owner: ref.owner,
+        description: api.description,
+        url: api.html_url,
+        stars: api.stargazers_count ?? 0,
+        forks: api.forks_count ?? 0,
+        watchers: api.subscribers_count ?? 0,
+        language: api.language,
+        topics: api.topics ?? [],
+        archived: api.archived ?? false,
+        isFork: api.fork ?? false,
+        private: false,
+        createdAt: api.created_at ?? "",
+        updatedAt: api.updated_at ?? "",
+        pushedAt: api.pushed_at ?? "",
+        score: 0,
+      };
+    }
+  } catch (err) {
+    // Let the not-found error propagate; only network/parse failures degrade
+    // to the stub below.
+    if (err instanceof Error && err.message.startsWith("Repo not found")) {
+      throw err;
+    }
+    // Fall through to the stub.
+  }
+  return repoFromRef(canonical);
+}
+
 /** Language breakdown: { [lang]: bytes } */
 type LanguageMap = Record<string, number>;
 
@@ -27,11 +140,31 @@ export interface DeepDiveData {
   readme: string;
 }
 
-/** Fetch all deep-dive data for a repo. Returns formatted sections. */
-export async function fetchDeepDive(
+/** Structured deep-dive payload — JSON-ready (for `ghfind deep-dive --json`). */
+export interface DeepDiveJson {
+  repo: {
+    fullName: string;
+    url: string;
+    description: string | null;
+    stars: number;
+    forks: number;
+    language: string | null;
+    topics: string[];
+  };
+  /** Language breakdown sorted by bytes, descending. */
+  languages: { name: string; bytes: number; percent: number }[];
+  contributors: { login: string; contributions: number }[];
+  /** Raw README markdown (capped at README_MAX_CHARS). */
+  readme: string;
+}
+
+const README_MAX_CHARS = 5_000;
+
+/** Fetch deep-dive data as structured JSON: language percents, contributors, raw README. */
+export async function fetchDeepDiveRaw(
   repo: Repo,
   token?: string,
-): Promise<DeepDiveData> {
+): Promise<DeepDiveJson> {
   const headers = buildHeaders(token);
 
   const [languagesRes, contributorsRes] = await Promise.all([
@@ -60,22 +193,64 @@ export async function fetchDeepDive(
     }
   }
 
+  const langEntries: [string, number][] = languagesRes.ok
+    ? Object.entries(
+        (await languagesRes.json().catch(() => ({}))) as LanguageMap,
+      )
+    : [];
+  const totalBytes = langEntries.reduce((s, [, v]) => s + v, 0);
+  const contributors: Contributor[] = contributorsRes.ok
+    ? ((await contributorsRes.json().catch(() => [])) as Contributor[])
+    : [];
+
+  return {
+    repo: {
+      fullName: repo.fullName,
+      url: repo.url,
+      description: repo.description,
+      stars: repo.stars,
+      forks: repo.forks,
+      language: repo.language,
+      topics: repo.topics,
+    },
+    languages: langEntries
+      .sort(([, a], [, b]) => b - a)
+      .map(([name, bytes]) => ({
+        name,
+        bytes,
+        percent: totalBytes > 0 ? (bytes / totalBytes) * 100 : 0,
+      })),
+    contributors: contributors.map((c) => ({
+      login: c.login,
+      contributions: c.contributions,
+    })),
+    readme: readmeText.slice(0, README_MAX_CHARS),
+  };
+}
+
+/** JSON string for `ghfind deep-dive --json`. */
+export function buildDeepDiveJson(data: DeepDiveJson): string {
+  return JSON.stringify(data, null, 2);
+}
+
+/** Format structured deep-dive data into display sections. */
+export function buildDeepDiveData(repo: Repo, raw: DeepDiveJson): DeepDiveData {
   return {
     summary: formatSummary(repo),
-    languages: formatLanguages(
-      languagesRes.ok
-        ? ((await languagesRes.json().catch(() => ({}))) as LanguageMap)
-        : {},
-    ),
-    contributors: formatContributors(
-      contributorsRes.ok
-        ? ((await contributorsRes.json().catch(() => [])) as Contributor[])
-        : [],
-    ),
-    readme: formatReadme(readmeText),
+    languages: formatLanguages(raw.languages),
+    contributors: formatContributors(raw.contributors),
+    readme: formatReadme(raw.readme),
   };
 }
 
+/** Fetch all deep-dive data for a repo. Returns formatted sections. */
+export async function fetchDeepDive(
+  repo: Repo,
+  token?: string,
+): Promise<DeepDiveData> {
+  return buildDeepDiveData(repo, await fetchDeepDiveRaw(repo, token));
+}
+
 function formatSummary(repo: Repo): string {
   const lines = [
     ` ${repo.fullName}`,
@@ -87,17 +262,14 @@ function formatSummary(repo: Repo): string {
   return lines.filter(Boolean).join("\n");
 }
 
-function formatLanguages(langs: LanguageMap): string {
-  const entries = Object.entries(langs);
-  if (entries.length === 0) return "  (no language data)";
-  const total = entries.reduce((s, [, v]) => s + v, 0);
+function formatLanguages(langs: DeepDiveJson["languages"]): string {
+  if (langs.length === 0) return "  (no language data)";
   const barW = 20;
-  return entries
-    .sort(([, a], [, b]) => b - a)
+  return langs
     .slice(0, 8)
-    .map(([name, bytes]) => {
-      const pct = ((bytes / total) * 100).toFixed(1);
-      const filled = Math.round((bytes / total) * barW);
+    .map(({ name, percent }) => {
+      const pct = percent.toFixed(1);
+      const filled = Math.round((percent / 100) * barW);
       const bar = "█".repeat(filled) + "░".repeat(barW - filled);
       return `  ${name.padEnd(16)} ${bar} ${pct}%`;
     })