github-search-cli 9.4.1 → 9.4.3

package/src/errors.ts

@@ -1,59 +1,62 @@
-/** Structured error types with user-facing messages. */
-
-export class SearchCliError extends Error {
-  constructor(
-    message: string,
-    public readonly userMessage: string,
-    public readonly recoverable: boolean = true,
-  ) {
-    super(message);
-    this.name = "SearchCliError";
-  }
-}
-
-export class NetworkError extends SearchCliError {
-  constructor() {
-    super(
-      "Network request failed",
-      "⚠ Network error — check your connection. Retrying in 5s... [r]etry now",
-    );
-    this.name = "NetworkError";
-  }
-}
-
-export class RateLimitError extends SearchCliError {
-  constructor(public readonly hasToken: boolean, resetSeconds?: number) {
-    const msg = hasToken
-      ? `⚠ API rate limit exceeded (5,000/hr). Resets in ${resetSeconds ?? "?"}s. [r]etry [c]hange token`
-      : "⚠ Rate limited (60/hr). Set GITHUB_TOKEN for 5,000/hr. [r]etry";
-    super(msg, msg);
-    this.name = "RateLimitError";
-  }
-}
-
-export class BadQueryError extends SearchCliError {
-  constructor(public readonly detail: string) {
-    super(`Invalid query: ${detail}`, `⚠ Invalid query: ${detail}`);
-    this.name = "BadQueryError";
-  }
-}
-
-export class NoResultsError extends SearchCliError {
-  constructor(public readonly query: string) {
-    super(
-      `No results for "${query}"`,
-      `🔍 No results for "${query}". Tips: check spelling, try fewer qualifiers, or [b]rowse trending`,
-    );
-    this.name = "NoResultsError";
-  }
-}
-
-export class ParseError extends SearchCliError {
-  constructor(source: string, detail: string) {
-    super(
-      `Parse error from ${source}: ${detail}`,
-      `⚠ Could not parse ${source}. GitHub may have changed the layout. [r]etry`,
-    );
-    this.name = "ParseError";
-  }
-}
+/** Structured error types with user-facing messages. */
+
+export class SearchCliError extends Error {
+  constructor(
+    message: string,
+    public readonly userMessage: string,
+    public readonly recoverable: boolean = true,
+  ) {
+    super(message);
+    this.name = "SearchCliError";
+  }
+}
+
+export class NetworkError extends SearchCliError {
+  constructor() {
+    super(
+      "Network request failed",
+      "⚠ Network error — check your connection. Retrying in 5s... [r]etry now",
+    );
+    this.name = "NetworkError";
+  }
+}
+
+export class RateLimitError extends SearchCliError {
+  constructor(
+    public readonly hasToken: boolean,
+    resetSeconds?: number,
+  ) {
+    const msg = hasToken
+      ? `⚠ API rate limit exceeded (5,000/hr). Resets in ${resetSeconds ?? "?"}s. [r]etry [c]hange token`
+      : "⚠ Rate limited (60/hr). Set GITHUB_TOKEN for 5,000/hr. [r]etry";
+    super(msg, msg);
+    this.name = "RateLimitError";
+  }
+}
+
+export class BadQueryError extends SearchCliError {
+  constructor(public readonly detail: string) {
+    super(`Invalid query: ${detail}`, `⚠ Invalid query: ${detail}`);
+    this.name = "BadQueryError";
+  }
+}
+
+export class NoResultsError extends SearchCliError {
+  constructor(public readonly query: string) {
+    super(
+      `No results for "${query}"`,
+      `🔍 No results for "${query}". Tips: check spelling, try fewer qualifiers, or [b]rowse trending`,
+    );
+    this.name = "NoResultsError";
+  }
+}
+
+export class ParseError extends SearchCliError {
+  constructor(source: string, detail: string) {
+    super(
+      `Parse error from ${source}: ${detail}`,
+      `⚠ Could not parse ${source}. GitHub may have changed the layout. [r]etry`,
+    );
+    this.name = "ParseError";
+  }
+}

package/src/explore.ts

@@ -1,29 +1,34 @@
-/**
- * Topic explorer — browse popular GitHub topics.
- * 
- * Selecting a topic triggers a search.
- */
-export interface TopicItem {
-  name: string;
-  description: string;
-  repoCount: number;
-}
-
-/** Fetch popular topics from GitHub search API.
- *  Requires the `mercy-preview` media type for the /search/topics endpoint.
- */
-export async function fetchTopics(): Promise<TopicItem[]> {
-  const res = await fetch("https://api.github.com/search/topics?q=popular&per_page=30", {
-    headers: {
-      Accept: "application/vnd.github.mercy-preview+json",
-      "User-Agent": "search-cli",
-    },
-  });
-  if (!res.ok) throw new Error(`Topics API: HTTP ${res.status}`);
-  const data = await res.json() as { items?: Array<{ name: string; description?: string; score?: number }> };
-  return (data.items ?? []).map((item) => ({
-    name: item.name,
-    description: item.description || "",
-    repoCount: item.score || 0,
-  }));
-}
+/**
+ * Topic explorer — browse popular GitHub topics.
+ *
+ * Selecting a topic triggers a search.
+ */
+export interface TopicItem {
+  name: string;
+  description: string;
+  repoCount: number;
+}
+
+/** Fetch popular topics from GitHub search API.
+ *  Requires the `mercy-preview` media type for the /search/topics endpoint.
+ */
+export async function fetchTopics(): Promise<TopicItem[]> {
+  const res = await fetch(
+    "https://api.github.com/search/topics?q=popular&per_page=30",
+    {
+      headers: {
+        Accept: "application/vnd.github.mercy-preview+json",
+        "User-Agent": "search-cli",
+      },
+    },
+  );
+  if (!res.ok) throw new Error(`Topics API: HTTP ${res.status}`);
+  const data = (await res.json()) as {
+    items?: Array<{ name: string; description?: string; score?: number }>;
+  };
+  return (data.items ?? []).map((item) => ({
+    name: item.name,
+    description: item.description || "",
+    repoCount: item.score || 0,
+  }));
+}

package/src/export.ts

@@ -1,63 +1,73 @@
-/**
- * Export — format repos as JSON, CSV, Markdown, or plain text.
- */
-import { writeFileSync } from "fs";
-import type { Repo } from "./types";
-
-export type ExportFormat = "json" | "csv" | "markdown" | "text";
-
-export function formatJson(repos: Repo[]): string {
-  return JSON.stringify(repos, 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;
-}
-
-/** Format repos as CSV string. */
-export function formatCsv(repos: Repo[]): string {
-  const header = "rank,full_name,stars,forks,language,url";
-  const rows = repos.map((r, i) =>
-    `${i + 1},${csvEscape(r.fullName)},${r.stars},${r.forks},${csvEscape(r.language ?? "")},${csvEscape(r.url)}`,
-  );
-  return [header, ...rows].join("\n");
-}
-
-/** Format repos as Markdown table. */
-export function formatMarkdown(repos: Repo[]): string {
-  const header = "| # | Repo | Stars | Forks | Language |";
-  const sep = "|---|------|-------|-------|----------|";
-  const rows = repos.map(
-    (r, i) =>
-      `| ${i + 1} | [${r.fullName}](${r.url}) | ${r.stars.toLocaleString()} | ${r.forks.toLocaleString()} | ${r.language ?? "—"} |`,
-  );
-  return [header, sep, ...rows].join("\n");
-}
-
-/** Format repos as plain text, one per line. */
-export function formatText(repos: Repo[]): string {
-  return repos.map((r, i) => `${i + 1}. ${r.fullName} ★ ${r.stars.toLocaleString()} ${r.url}`).join("\n");
-}
-
-/** Format repos in the given format. */
-export function formatRepos(repos: Repo[], format: ExportFormat): string {
-  switch (format) {
-    case "json": return formatJson(repos);
-    case "csv": return formatCsv(repos);
-    case "markdown": return formatMarkdown(repos);
-    case "text": return formatText(repos);
-  }
-}
-
-/** Export repos to a file. Returns the file path. */
-export function exportToFile(repos: Repo[], format: ExportFormat): string {
-  const ext = format === "markdown" ? "md" : format;
-  const ts = Date.now();
-  const path = `./ghfind-export-${ts}.${ext}`;
-  writeFileSync(path, formatRepos(repos, format), "utf-8");
-  return path;
-}
+/**
+ * Export — format repos as JSON, CSV, Markdown, or plain text.
+ */
+import { writeFileSync } from "fs";
+import type { Repo } from "./types";
+
+export type ExportFormat = "json" | "csv" | "markdown" | "text";
+
+export function formatJson(repos: Repo[]): string {
+  return JSON.stringify(repos, 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;
+}
+
+/** Format repos as CSV string. */
+export function formatCsv(repos: Repo[]): string {
+  const header = "rank,full_name,stars,forks,language,url";
+  const rows = repos.map(
+    (r, i) =>
+      `${i + 1},${csvEscape(r.fullName)},${r.stars},${r.forks},${csvEscape(r.language ?? "")},${csvEscape(r.url)}`,
+  );
+  return [header, ...rows].join("\n");
+}
+
+/** Format repos as Markdown table. */
+export function formatMarkdown(repos: Repo[]): string {
+  const header = "| # | Repo | Stars | Forks | Language |";
+  const sep = "|---|------|-------|-------|----------|";
+  const rows = repos.map(
+    (r, i) =>
+      `| ${i + 1} | [${r.fullName}](${r.url}) | ${r.stars.toLocaleString()} | ${r.forks.toLocaleString()} | ${r.language ?? "—"} |`,
+  );
+  return [header, sep, ...rows].join("\n");
+}
+
+/** Format repos as plain text, one per line. */
+export function formatText(repos: Repo[]): string {
+  return repos
+    .map(
+      (r, i) =>
+        `${i + 1}. ${r.fullName} ★ ${r.stars.toLocaleString()} ${r.url}`,
+    )
+    .join("\n");
+}
+
+/** Format repos in the given format. */
+export function formatRepos(repos: Repo[], format: ExportFormat): string {
+  switch (format) {
+    case "json":
+      return formatJson(repos);
+    case "csv":
+      return formatCsv(repos);
+    case "markdown":
+      return formatMarkdown(repos);
+    case "text":
+      return formatText(repos);
+  }
+}
+
+/** Export repos to a file. Returns the file path. */
+export function exportToFile(repos: Repo[], format: ExportFormat): string {
+  const ext = format === "markdown" ? "md" : format;
+  const ts = Date.now();
+  const path = `./ghfind-export-${ts}.${ext}`;
+  writeFileSync(path, formatRepos(repos, format), "utf-8");
+  return path;
+}

package/src/help.ts

@@ -1,157 +1,157 @@
-/** Help screen — structured sections rendered by OpenTUI components. */
-export interface HelpRow {
-  keys: string;
-  action: string;
-}
-export interface HelpSection {
-  title: string;
-  /** Theme color key or hex — used for Box title color */
-  titleColor: string;
-  rows: HelpRow[];
-  note?: string;
-}
-export function buildHelpSections(): HelpSection[] {
-  return [
-    {
-      title: " Landing ",
-      titleColor: "blue",
-      rows: [
-        { keys: "↑ ↓ / j k", action: "Navigate menu cards" },
-        { keys: "Enter", action: "Select mode / open Bookmarks" },
-        { keys: "b", action: "Jump straight to Bookmarks" },
-        { keys: "? / h", action: "Toggle this help screen" },
-        { keys: "q", action: "Quit" },
-      ],
-    },
-    {
-      title: " Navigation ",
-      titleColor: "blue",
-      rows: [
-        { keys: "↑ ↓ / j k", action: "Move selection" },
-        { keys: "Enter", action: "Open repo in browser" },
-        { keys: "/", action: "Focus search input" },
-        { keys: "Space", action: "Open command menu" },
-        { keys: "? / Ctrl+H", action: "Toggle this help screen" },
-        { keys: "q", action: "Quit" },
-      ],
-    },
-    {
-      title: " Main View ",
-      titleColor: "green",
-      rows: [
-        { keys: "Tab", action: "Auto-complete qualifier" },
-        { keys: "b", action: "Bookmark / unbookmark selected repo" },
-        { keys: "c", action: "Compare selected repo" },
-        { keys: "t", action: "Cycle theme" },
-        { keys: "PageDown", action: "Next page of results" },
-        { keys: "PageUp", action: "Scroll to top of results" },
-      ],
-    },
-    {
-      title: " Trending Mode ",
-      titleColor: "yellow",
-      rows: [
-        { keys: "1-5", action: "Switch tab: Today → Week → Month → …" },
-        { keys: "← → / h l", action: "Navigate tabs" },
-      ],
-    },
-    {
-      title: " Packages Mode ",
-      titleColor: "cyan",
-      rows: [
-        { keys: "/", action: "Search npm packages" },
-        { keys: "↑ ↓ / j k", action: "Move selection" },
-        { keys: "Enter", action: "View package details" },
-        { keys: "Space", action: "Open command menu" },
-      ],
-      note: "Search by name, description, or tags. Sort by downloads or score.",
-    },
-    {
-      title: " Command Menu (Space)",
-      titleColor: "purple",
-      rows: [
-        { keys: "Sort", action: "Cycle sort: best-match → stars → …" },
-        { keys: "Limit", action: "Cycle limit: 10 → 25 → 50 → 100" },
-        { keys: "Refresh", action: "Re-run current search" },
-        { keys: "Graph", action: "Toggle commit activity chart" },
-        { keys: "Readme", action: "Full README viewer" },
-        { keys: "Deep-dive", action: "Languages + contributors + excerpt" },
-        { keys: "Bookmark", action: "Save / unsave selected repo" },
-        { keys: "Compare", action: "Add to / remove from comparison" },
-        { keys: "Trending", action: "Switch to trending browser" },
-        { keys: "Packages", action: "Switch to npm packages" },
-        { keys: "Export", action: "Export results to file" },
-        { keys: "Share", action: "Share repo as text" },
-        { keys: "Topics", action: "Browse GitHub topics" },
-        { keys: "Saved", action: "View saved searches" },
-        { keys: "Notifs", action: "Check GitHub notifications" },
-        { keys: "History", action: "View search history" },
-        { keys: "Help", action: "Show this help screen" },
-      ],
-      note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc",
-    },
-    {
-      title: " Bookmarks Page ",
-      titleColor: "green",
-      rows: [
-        { keys: "↑ ↓ / j k", action: "Move selection" },
-        { keys: "Enter", action: "Open bookmark in browser" },
-        { keys: "d", action: "Remove bookmark" },
-        { keys: "Esc / ←", action: "Back to landing" },
-      ],
-      note: "A full page, not an overlay — Esc returns to the mode menu.",
-    },
-    {
-      title: " Overlay Keys ",
-      titleColor: "teal",
-      rows: [
-        { keys: "Esc / q", action: "Close any overlay" },
-        { keys: "Enter", action: "Confirm selection / run action" },
-        { keys: "d", action: "Delete entry (history, saved)" },
-        { keys: "↑ ↓ / j k", action: "Navigate overlay list" },
-        { keys: "← → / h l", action: "Navigate tabs / panels" },
-      ],
-    },
-    {
-      title: " Search Syntax ",
-      titleColor: "teal",
-      rows: [
-        { keys: "keywords", action: "Free-text search" },
-        { keys: "key:value", action: "Qualifier filter" },
-        { keys: "-key:value", action: "Negated qualifier" },
-        { keys: '"phrase"', action: "Exact phrase match" },
-        { keys: "language:TypeScript", action: "Filter by language" },
-        { keys: "stars:>1000", action: "Minimum stars" },
-        { keys: "fork:true", action: "Include forks" },
-        { keys: "user:octocat", action: "User's repos" },
-        { keys: "org:facebook", action: "Organization repos" },
-        { keys: "repo:facebook/react", action: "Specific repo" },
-        { keys: "topic:react", action: "Filter by topic" },
-        { keys: "license:mit", action: "License type" },
-        { keys: "pushed:>2024-01-01", action: "Last push date" },
-        { keys: "archived:false", action: "Exclude archived" },
-      ],
-    },
-    {
-      title: " Utility Keys ",
-      titleColor: "muted",
-      rows: [
-        { keys: "t", action: "Cycle theme (light / dark / solarized)" },
-        { keys: "Ctrl+X", action: "Copy repo URL to clipboard" },
-        { keys: "Ctrl+C", action: "Copy search query to clipboard" },
-      ],
-    },
-    {
-      title: " Rate Limits ",
-      titleColor: "orange",
-      rows: [
-        { keys: "No token", action: "10 req / min" },
-        { keys: "GITHUB_TOKEN", action: "30 req / min (or your plan limit)" },
-      ],
-      note: "Set GITHUB_TOKEN in your environment or add to config.",
-    },
-  ];
-}
-
-/** Column at which the action description starts (right-aligns keys). */
-export const HELP_KEYS_COLUMN = 24;
+/** Help screen — structured sections rendered by OpenTUI components. */
+export interface HelpRow {
+  keys: string;
+  action: string;
+}
+export interface HelpSection {
+  title: string;
+  /** Theme color key or hex — used for Box title color */
+  titleColor: string;
+  rows: HelpRow[];
+  note?: string;
+}
+export function buildHelpSections(): HelpSection[] {
+  return [
+    {
+      title: " Landing ",
+      titleColor: "blue",
+      rows: [
+        { keys: "↑ ↓ / j k", action: "Navigate menu cards" },
+        { keys: "Enter", action: "Select mode / open Bookmarks" },
+        { keys: "b", action: "Jump straight to Bookmarks" },
+        { keys: "? / h", action: "Toggle this help screen" },
+        { keys: "q", action: "Quit" },
+      ],
+    },
+    {
+      title: " Navigation ",
+      titleColor: "blue",
+      rows: [
+        { keys: "↑ ↓ / j k", action: "Move selection" },
+        { keys: "Enter", action: "Open repo in browser" },
+        { keys: "/", action: "Focus search input" },
+        { keys: "Space", action: "Open command menu" },
+        { keys: "? / Ctrl+H", action: "Toggle this help screen" },
+        { keys: "q", action: "Quit" },
+      ],
+    },
+    {
+      title: " Main View ",
+      titleColor: "green",
+      rows: [
+        { keys: "Tab", action: "Auto-complete qualifier" },
+        { keys: "b", action: "Bookmark / unbookmark selected repo" },
+        { keys: "c", action: "Compare selected repo" },
+        { keys: "t", action: "Cycle theme" },
+        { keys: "PageDown", action: "Next page of results" },
+        { keys: "PageUp", action: "Scroll to top of results" },
+      ],
+    },
+    {
+      title: " Trending Mode ",
+      titleColor: "yellow",
+      rows: [
+        { keys: "1-5", action: "Switch tab: Today → Week → Month → …" },
+        { keys: "← → / h l", action: "Navigate tabs" },
+      ],
+    },
+    {
+      title: " Packages Mode ",
+      titleColor: "cyan",
+      rows: [
+        { keys: "/", action: "Search npm packages" },
+        { keys: "↑ ↓ / j k", action: "Move selection" },
+        { keys: "Enter", action: "View package details" },
+        { keys: "Space", action: "Open command menu" },
+      ],
+      note: "Search by name, description, or tags. Sort by downloads or score.",
+    },
+    {
+      title: " Command Menu (Space)",
+      titleColor: "purple",
+      rows: [
+        { keys: "Sort", action: "Cycle sort: best-match → stars → …" },
+        { keys: "Limit", action: "Cycle limit: 10 → 25 → 50 → 100" },
+        { keys: "Refresh", action: "Re-run current search" },
+        { keys: "Graph", action: "Toggle commit activity chart" },
+        { keys: "Readme", action: "Full README viewer" },
+        { keys: "Deep-dive", action: "Languages + contributors + excerpt" },
+        { keys: "Bookmark", action: "Save / unsave selected repo" },
+        { keys: "Compare", action: "Add to / remove from comparison" },
+        { keys: "Trending", action: "Switch to trending browser" },
+        { keys: "Packages", action: "Switch to npm packages" },
+        { keys: "Export", action: "Export results to file" },
+        { keys: "Share", action: "Share repo as text" },
+        { keys: "Topics", action: "Browse GitHub topics" },
+        { keys: "Saved", action: "View saved searches" },
+        { keys: "Notifs", action: "Check GitHub notifications" },
+        { keys: "History", action: "View search history" },
+        { keys: "Help", action: "Show this help screen" },
+      ],
+      note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc",
+    },
+    {
+      title: " Bookmarks Page ",
+      titleColor: "green",
+      rows: [
+        { keys: "↑ ↓ / j k", action: "Move selection" },
+        { keys: "Enter", action: "Open bookmark in browser" },
+        { keys: "d", action: "Remove bookmark" },
+        { keys: "Esc / ←", action: "Back to landing" },
+      ],
+      note: "A full page, not an overlay — Esc returns to the mode menu.",
+    },
+    {
+      title: " Overlay Keys ",
+      titleColor: "teal",
+      rows: [
+        { keys: "Esc / q", action: "Close any overlay" },
+        { keys: "Enter", action: "Confirm selection / run action" },
+        { keys: "d", action: "Delete entry (history, saved)" },
+        { keys: "↑ ↓ / j k", action: "Navigate overlay list" },
+        { keys: "← → / h l", action: "Navigate tabs / panels" },
+      ],
+    },
+    {
+      title: " Search Syntax ",
+      titleColor: "teal",
+      rows: [
+        { keys: "keywords", action: "Free-text search" },
+        { keys: "key:value", action: "Qualifier filter" },
+        { keys: "-key:value", action: "Negated qualifier" },
+        { keys: '"phrase"', action: "Exact phrase match" },
+        { keys: "language:TypeScript", action: "Filter by language" },
+        { keys: "stars:>1000", action: "Minimum stars" },
+        { keys: "fork:true", action: "Include forks" },
+        { keys: "user:octocat", action: "User's repos" },
+        { keys: "org:facebook", action: "Organization repos" },
+        { keys: "repo:facebook/react", action: "Specific repo" },
+        { keys: "topic:react", action: "Filter by topic" },
+        { keys: "license:mit", action: "License type" },
+        { keys: "pushed:>2024-01-01", action: "Last push date" },
+        { keys: "archived:false", action: "Exclude archived" },
+      ],
+    },
+    {
+      title: " Utility Keys ",
+      titleColor: "muted",
+      rows: [
+        { keys: "t", action: "Cycle theme (light / dark / solarized)" },
+        { keys: "Ctrl+X", action: "Copy repo URL to clipboard" },
+        { keys: "Ctrl+C", action: "Copy search query to clipboard" },
+      ],
+    },
+    {
+      title: " Rate Limits ",
+      titleColor: "orange",
+      rows: [
+        { keys: "No token", action: "10 req / min" },
+        { keys: "GITHUB_TOKEN", action: "30 req / min (or your plan limit)" },
+      ],
+      note: "Set GITHUB_TOKEN in your environment or add to config.",
+    },
+  ];
+}
+
+/** Column at which the action description starts (right-aligns keys). */
+export const HELP_KEYS_COLUMN = 24;