github-search-cli 0.6.1 → 0.7.0

package/src/help.ts

@@ -1,46 +1,120 @@
-/**
- * Help screen: full keyboard shortcut reference for the TUI.
- */
-export function buildHelpText(): string {
-  return [
-    "┌─ search-cli Help ──────────────────────────── [q] close ─┐",
-    "│                                                           │",
-    "│  NAVIGATION                                              │",
-    "│    ↑ ↓ / j k     Move selection                         │",
-    "│    Enter / o      Open repo in browser                   │",
-    "│    /              Focus search input                     │",
-    "│    t              Toggle search / trending               │",
-    "│    ? / Ctrl+H     Toggle this help screen                │",
-    "│    q              Quit                                   │",
-    "│                                                           │",
-    "│  SEARCH MODE                                             │",
-    "│    s              Cycle sort: best-match → stars → ...  │",
-    "│    l              Cycle limit: 10 → 25 → 50 → 100       │",
-    "│    r              Refresh / re-run last search           │",
-    "│    g              Toggle activity graph fullscreen       │",
-    "│    Tab            Auto-complete qualifier                │",
-    "│                                                           │",
-    "│  TRENDING MODE                                           │",
-    "│    1-5            Switch tab: Today → Week → Month → ...│",
-    "│    ← → / h l     Navigate tabs                           │",
-    "│    r              Refresh                                 │",
-    "│                                                           │",
-    "│  SEARCH SYNTAX                                           │",
-    "│    keywords       Free-text search                       │",
-    "│    key:value      Qualifier filter                       │",
-    "│    -key:value     Negated qualifier                      │",
-    "│    \"phrase\"      Exact phrase match                     │",
-    "│                                                           │",
-    "│  QUALIFIERS                                              │",
-    "│    language:  Stars:    Fork:     Archived:  Topic:      │",
-    "│    user:      Org:      Repo:     Updated:   Pushed:     │",
-    "│    visibility: License: Created:  Size:      In:         │",
-    "│                                                           │",
-    "│  RATE LIMITS                                             │",
-    "│    No token       10 req/min                            │",
-    "│    GITHUB_TOKEN   30 req/min (or your plan limit)        │",
-    "│                                                           │",
-    "│  Set GITHUB_TOKEN in your environment or add to config.  │",
-    "└───────────────────────────────────────────────────────────┘",
-  ].join("\n");
-}
+/**
+ * Help screen — structured sections rendered by OpenTUI components.
+ *
+ * Each section has a title (with category color) and formatted rows.
+ * The TUI builds these into Box + TextRenderable components inside a ScrollBox.
+ */
+
+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: " Navigation ",
+      titleColor: "blue",
+      rows: [
+        { keys: "↑ ↓ / j k", action: "Move selection" },
+        { keys: "Enter / o", action: "Open repo in browser" },
+        { keys: "/", action: "Focus search input" },
+        { keys: "t", action: "Toggle search / trending" },
+        { keys: "? / Ctrl+H", action: "Toggle this help screen" },
+        { keys: "q", action: "Quit" },
+      ],
+    },
+    {
+      title: " Search Mode ",
+      titleColor: "green",
+      rows: [
+        { keys: "s", action: "Cycle sort: best-match → stars → …" },
+        { keys: "l", action: "Cycle limit: 10 → 25 → 50 → 100" },
+        { keys: "r", action: "Refresh / re-run last search" },
+        { keys: "g", action: "Toggle activity graph fullscreen" },
+        { keys: "Tab", action: "Auto-complete qualifier" },
+        { keys: "b", action: "Bookmark / unbookmark selected repo" },
+      ],
+    },
+    {
+      title: " Trending Mode ",
+      titleColor: "yellow",
+      rows: [
+        { keys: "1-5", action: "Switch tab: Today → Week → Month → …" },
+        { keys: "← → / h l", action: "Navigate tabs" },
+        { keys: "r", action: "Refresh" },
+      ],
+    },
+    {
+      title: " Power Tools ",
+      titleColor: "purple",
+      rows: [
+        { keys: "d", action: "Deep-dive: README + commit activity" },
+        { keys: "c", action: "Add/remove repo from comparison" },
+        { keys: "C (Shift+c)", action: "Show comparison view" },
+        { keys: "E (Shift+e)", action: "Topic explorer" },
+        { keys: "B (Shift+b)", action: "Bookmarks panel" },
+        { keys: "PageDown / Ctrl+F", action: "Next page of results" },
+        { keys: "PageUp / Ctrl+B", action: "Scroll to top of results" },
+      ],
+    },
+    {
+      title: " Overlays ",
+      titleColor: "teal",
+      rows: [
+        { keys: "Ctrl+R", action: "Search history" },
+        { keys: "Ctrl+O", action: "Saved searches" },
+        { keys: "Ctrl+E", action: "Export results" },
+        { keys: "Ctrl+N", action: "Notifications" },
+        { keys: "Ctrl+S", action: "Save current search" },
+        { keys: "Ctrl+P", action: "Share selected repo" },
+      ],
+    },
+    {
+      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" },
+      ],
+    },
+    {
+      title: " Qualifiers ",
+      titleColor: "muted",
+      rows: [
+        { keys: "language:", action: "Filter by language" },
+        { keys: "stars:>N", action: "Minimum stars" },
+        { keys: "fork:true", action: "Include forks" },
+        { keys: "user:", action: "User's repos" },
+        { keys: "org:", action: "Organization repos" },
+        { keys: "repo:", action: "Specific repo" },
+        { keys: "topic:", action: "Filter by topic" },
+        { keys: "license:", action: "License type" },
+        { keys: "pushed:>YYYY-MM-DD", action: "Last push date" },
+        { keys: "archived:false", action: "Exclude archived" },
+      ],
+    },
+    {
+      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;

package/src/init.ts

@@ -5,6 +5,7 @@
  */
 import { createInterface } from "readline";
 import { saveConfig } from "./config.ts";
+import { listThemes } from "./themes.ts";
 import type { Config, SortStrategy } from "./types.ts";
 
 function ask(query: string): Promise<string> {
@@ -24,15 +25,22 @@ export async function runInitWizard(): Promise<void> {
   console.log("");
 
   const token = await ask("  GitHub token (optional, press Enter to skip): ");
+  if (token && !token.startsWith("ghp_") && !token.startsWith("github_pat_") && !token.startsWith("gho_")) {
+    console.log("  ⚠ Token doesn't look like a GitHub token (should start with ghp_, gho_, or github_pat_)");
+  }
+
   const sortStr = await ask("  Default sort [best-match/stars/updated/forks] (best-match): ");
   const limitStr = await ask("  Default result limit [10-100] (50): ");
 
+  const themes = listThemes();
+  const themeStr = await ask(`  Theme [${themes.join("/")}] (tokyo-night): `);
+
   const config: Config = {
     defaultSort: (["best-match", "stars", "updated", "forks"].includes(sortStr)
       ? sortStr
       : "best-match") as SortStrategy,
     defaultLimit: Math.min(100, Math.max(10, parseInt(limitStr) || 50)),
-    theme: "tokyo-night",
+    theme: themes.includes(themeStr) ? themeStr : "tokyo-night",
     cacheTtlSeconds: 300,
     defaultTab: "search",
   };

package/src/normalizer.ts

@@ -37,26 +37,26 @@ export interface GitHubSearchEnvelope {
 
 /** Convert a single GitHub API item into a {@link Repo}. */
 export function normalizeRepo(item: GitHubApiItem): Repo {
-  const owner = item.owner?.login ?? item.full_name.split("/")[0] ?? "";
+  const owner = item.owner?.login ?? item.full_name?.split("/")[0] ?? "";
   return {
-    id: item.id,
-    fullName: item.full_name,
-    name: item.name,
+    id: item.id ?? 0,
+    fullName: item.full_name ?? "",
+    name: item.name ?? "",
     owner,
-    description: item.description,
-    url: item.html_url,
-    stars: item.stargazers_count,
-    forks: item.forks_count,
-    watchers: item.watchers_count,
-    language: item.language,
+    description: item.description ?? null,
+    url: item.html_url ?? "",
+    stars: item.stargazers_count ?? 0,
+    forks: item.forks_count ?? 0,
+    watchers: item.watchers_count ?? 0,
+    language: item.language ?? null,
     topics: item.topics ?? [],
-    archived: item.archived,
-    isFork: item.fork,
-    private: item.private,
-    createdAt: item.created_at,
-    updatedAt: item.updated_at,
-    pushedAt: item.pushed_at,
-    score: item.score,
+    archived: item.archived ?? false,
+    isFork: item.fork ?? false,
+    private: item.private ?? false,
+    createdAt: item.created_at ?? "",
+    updatedAt: item.updated_at ?? "",
+    pushedAt: item.pushed_at ?? "",
+    score: item.score ?? 0,
   };
 }
 

package/src/open-url.ts

@@ -0,0 +1,17 @@
+/**
+ * Open a URL in the user's default browser — platform-aware.
+ *
+ * ponytail: three platforms, no abstraction. Add more browsers/flags
+ * only if the open/xdg-open pattern fails somewhere.
+ */
+
+export function openUrl(url: string): void {
+  try {
+    const p = process.platform;
+    if (p === "win32") Bun.spawn(["cmd", "/c", "start", "", url]);
+    else if (p === "darwin") Bun.spawn(["open", url]);
+    else Bun.spawn(["xdg-open", url]);
+  } catch {
+    // non-critical — user can copy the URL manually
+  }
+}

package/src/output.ts

@@ -5,9 +5,10 @@
  */
 import type { Repo, SearchResponse } from "./types.ts";
 
-/** Format a number compactly (e.g. 1234 -> "1.2k"). */
+/** Format a number compactly (e.g. 1234 -> "1.2k", 999999 -> "1M"). */
 export function formatCount(n: number): string {
   if (n < 1000) return String(n);
+  if (n >= 999_500) return "1M"; // ponytail: round 999500+ up before showing 1000k
   if (n < 1_000_000) return `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k`;
   return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
 }

package/src/pipe.ts

@@ -2,6 +2,7 @@
  * Pipe-friendly format modifiers — output repo data as lines for shell piping.
  */
 import type { Repo } from "./types.ts";
+import { openUrl } from "./open-url.ts";
 
 export type FormatLine = "urls" | "names" | "ssh-urls" | "clone-commands" | "ids";
 
@@ -56,10 +57,4 @@ export async function pipeExec(repos: Repo[], target: string): Promise<void> {
   }
 }
 
-async function openUrl(url: string): Promise<void> {
-  const p = process.platform;
-  const args = p === "win32" ? ["cmd", "/c", "start", "", url]
-    : p === "darwin" ? ["open", url]
-    : ["xdg-open", url];
-  Bun.spawn(args);
-}
+

package/src/provider.ts

@@ -89,15 +89,22 @@ export class GitHubSearchProvider implements SearchProvider {
             },
           });
 
-          rateLimitRemaining = Number(res.headers.get("x-ratelimit-remaining") ?? NaN);
-          if (res.status === 403 && rateLimitRemaining === 0) {
-            if (this.tokens.length > 0 && attempt < this.tokens.length) {
-              // Token exhausted, try next
-              continue;
+          const remainingStr = res.headers.get("x-ratelimit-remaining");
+          rateLimitRemaining = remainingStr !== null ? Number(remainingStr) : undefined;
+          if (res.status === 403) {
+            if (remainingStr === "0" || remainingStr === null) {
+              // Rate limited
+              if (this.tokens.length > 0 && attempt < this.tokens.length) {
+                continue;
+              }
+              this.logger.warn("[github] rate limit exceeded");
+              rateLimited = true;
+              throw new RateLimitError(!!token);
             }
-            this.logger.warn("[github] rate limit exceeded");
-            rateLimited = true;
-            throw new RateLimitError(!!token);
+            // Non-rate-limit 403 (e.g. private repo, permissions)
+            const body = await res.text().catch(() => "");
+            this.logger.error(`[github] non-rate-limit 403: ${body.slice(0, 200)}`);
+            throw new NetworkError();
           }
           if (!res.ok) {
             const body = await res.text().catch(() => "");
@@ -105,7 +112,23 @@ export class GitHubSearchProvider implements SearchProvider {
             throw new NetworkError();
           }
 
-          const env = (await res.json()) as GitHubSearchEnvelope;
+          // Validate response is valid JSON before trusting the cast
+          const raw = await res.text();
+          let parsed: any;
+          try {
+            parsed = JSON.parse(raw);
+          } catch {
+            const snippet = raw.slice(0, 200);
+            this.logger.error(`[github] invalid JSON response: ${snippet}`);
+            throw new ParseError("GitHub API", snippet.includes("<!DOCTYPE")
+              ? "GitHub returned an HTML page (maintenance or CAPTCHA?)"
+              : "Invalid JSON response");
+          }
+          if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.items)) {
+            this.logger.error(`[github] unexpected response shape: ${JSON.stringify(parsed).slice(0, 200)}`);
+            throw new ParseError("GitHub API", "Unexpected response shape — missing items array");
+          }
+          const env = parsed as GitHubSearchEnvelope;
           totalCount = env.total_count;
           const repos = normalizeEnvelope(env);
           all.push(...repos);

package/src/query.ts

@@ -186,12 +186,9 @@ export function applyFlagFilters(
 export function validateQuery(query: ParsedQuery): void {
   const has = (key: string) => query.qualifiers.some((q) => q.key === key && !q.negated);
 
-  if (has("fork") && has("archived")) {
-    throw new Error("Cannot combine `fork:` and `archived:` filters (a fork can still be archived, but the combination is usually unintended).");
-  }
-  if (has("user") && has("org")) {
-    throw new Error("Cannot combine `user:` and `org:` filters (a repo belongs to one or the other).");
-  }
+  // ponytail: removed fork+archived and user+org validation — both are valid
+  // GitHub search queries (a fork can be archived; user: acts as author/committer
+  // not owner, so user+org is a valid scoping query).
   if (has("visibility") && has("private")) {
     throw new Error("Cannot combine `visibility:` and `private:` filters.");
   }
@@ -244,7 +241,8 @@ export function buildSearchUrl(query: ParsedQuery, options: SearchOptions): stri
   const q = buildGitHubQuery(query);
   const { sort, order } = githubSortParam(options.sort);
   const perPage = Math.min(Math.max(options.limit, 1), 100); // GitHub max page size
-  const params = new URLSearchParams({ q: q || " ", per_page: String(perPage) });
+  // ponytail: per_page is set by appendPage in provider, not here
+  const params = new URLSearchParams({ q: q || " " });
   if (sort) params.set("sort", sort);
   if (order) params.set("order", order);
   return `https://api.github.com/search/repositories?${params.toString()}`;

package/src/ranking.ts

@@ -27,9 +27,11 @@ export function rankRepos(repos: Repo[], strategy: SortStrategy): Repo[] {
       break;
     case "best-match":
     default:
-      // GitHub already returns best-match order; keep it but apply a stable
-      // tie-breaker so the output is reproducible.
-      copy.sort((a, b) => b.score - a.score || b.stars - a.stars || a.id - b.id);
+      // GitHub already returns best-match order; preserve it unchanged.
+      // Re-sorting by score would be redundant for first-page results and
+      // misleading for paginated (page 2 repos would intermix with page 1).
+      // ponytail: if deterministic output is needed, sort by id:
+      // copy.sort((a, b) => a.id - b.id);
       break;
   }
   return copy;

package/src/session.ts

@@ -12,8 +12,10 @@ export function saveSession(state: SessionState): void {
   mkdirSync(stateDir(), { recursive: true });
   try {
     writeFileSync(SESSION_FILE, JSON.stringify(state));
-  } catch {
-    // non-critical
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[search-cli] Failed to save session: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
 }
 

package/src/trending.ts

@@ -19,7 +19,9 @@ import {
   t,
 } from "@opentui/core";
 import type { Repo } from "./types.ts";
-import { NetworkError, ParseError } from "./errors.ts";
+import { openUrl } from "./open-url.ts";
+import { NetworkError } from "./errors.ts";
+import type { GitHubSearchEnvelope } from "./normalizer.ts";
 
 // ─── Tokyo Night palette ──────────────────────────────────────────────
 const C = {
@@ -80,12 +82,12 @@ function rankColor(rank: number): string {
 }
 
 // ─── Tab definitions ──────────────────────────────────────────────────
-export const TAB_NAMES = ["Today", "This Week", "This Month", "This Year", "All Time"] as const;
+export const TAB_NAMES = ["Today", "This Week", "This Month"] as const;
 export type TabName = (typeof TAB_NAMES)[number];
 
-/** Map TabName to GitHub trending ?since= parameter.
- *  Note: GitHub trending only offers daily/weekly/monthly.
- *  "This Year" and "All Time" fall back to monthly.
+/** Map TabName to GitHub API date range.
+ *  We use the search API with `created:>DATE&sort=stars` so only
+ *  daily/weekly/monthly ranges are meaningful.
  */
 export function tabSince(tab: TabName): "daily" | "weekly" | "monthly" {
   switch (tab) {
@@ -109,64 +111,53 @@ export interface TrendingRepo {
 // ─── Mock data ────────────────────────────────────────────────────────
 
 /**
- * Fetch real trending repos from github.com/trending.
- * Parses the HTML to extract owner, name, description, language, total stars,
- * and — crucially — stars gained in the period (daily/weekly/monthly).
+ * Fetch trending repos from the GitHub search API instead of HTML scraping.
+ * Uses `created:>DATE&sort=stars` queries since the API doesn't expose a
+ * dedicated trending endpoint.
+ *
+ * Note: `starsToday` is always 0 because the API doesn't provide period growth.
+ * The growth indicator is hidden when 0.
  */
 export async function fetchTrendingRepos(since: "daily" | "weekly" | "monthly"): Promise<TrendingRepo[]> {
-  const url = `https://github.com/trending?since=${since}`;
+  const now = Date.now();
+  const msPerDay = 86_400_000;
+  const days = since === "daily" ? 1 : since === "weekly" ? 7 : 30;
+  const date = new Date(now - days * msPerDay).toISOString().slice(0, 10);
+
+  const url = `https://api.github.com/search/repositories?q=created:>${date}&sort=stars&order=desc&per_page=25`;
   let res: Response;
   try {
-    res = await fetch(url, { headers: { "User-Agent": "search-cli/1.0" } });
+    res = await fetch(url, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "search-cli",
+      },
+    });
   } catch {
     throw new NetworkError();
   }
-  if (!res.ok) throw new ParseError("GitHub trending", `HTTP ${res.status}`);
-  const html = await res.text();
-
-  const repos: TrendingRepo[] = [];
-  const articles = html.split('<article class="Box-row">');
-  // first element is everything before the first article
-
-  for (let i = 1; i < articles.length; i++) {
-    const block = articles[i];
-    const rank = i; // 1-based
-
-    // Owner/name from the h2 anchor
-    const h2 = block.match(/<h2[^>]*>[\s\S]*?<a[^>]*href="\/([^"/]+)\/([^"/]+?)"/);
-    if (!h2) continue;
-    const owner = h2[1];
-    const name = h2[2];
-
-    // Description from <p>
-    const p = block.match(/<p[^>]*>([\s\S]*?)<\/p>/);
-    const description = p ? p[1].replace(/<[^>]*>/g, "").replace(/\s+/g, " ").trim() : "";
-
-    // Language
-    const lang = block.match(/programmingLanguage"[^>]*>([^<]+)</);
-    const language = lang ? lang[1].trim() : "";
-
-    // Total stars (text after star SVG and before </a>)
-    const stargazerBlock = block.match(/stargazers[^>]*>[\s\S]*?<\/svg>\s*([\d,]+)\s*<\/a>/);
-    const stars = stargazerBlock ? parseInt(stargazerBlock[1].replace(/,/g, "")) : 0;
-
-    // Stars gained this period (e.g. "8,795 stars this week")
-    const periodS = block.match(new RegExp(`([\\d,]+)\\s+stars\\s+this\\s+${since === "daily" ? "day" : since === "weekly" ? "week" : "month"}`));
-    const starsToday = periodS ? parseInt(periodS[1].replace(/,/g, "")) : 0;
-
-    repos.push({ rank, owner, name, stars, starsToday, language, description });
-  }
-
-  return repos;
+  if (!res.ok) throw new NetworkError();
+  const data = (await res.json()) as GitHubSearchEnvelope;
+
+  return data.items.map((item, i) => ({
+    rank: i + 1,
+    owner: item.owner?.login ?? "?",
+    name: item.name,
+    stars: item.stargazers_count,
+    starsToday: 0, // API doesn't provide period growth
+    language: item.language ?? "",
+    description: item.description ?? "",
+  }));
 }
 
 
 
 // ─── Number formatting ────────────────────────────────────────────────
 
-/** 1234 → "1.2k", 1234567 → "1.2M" */
+/** 1234 → "1.2k", 1234567 → "1.2M", 999999 → "1M" */
 export function fmtStars(n: number): string {
   if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (n >= 999_500) return "1M"; // ponytail: round 999500+ up before showing 1000k
   if (n >= 1_000) return `${(n / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
   return String(n);
 }
@@ -237,8 +228,6 @@ export function getTrendingQuery(tab: TabName): string {
     Today: 1,
     "This Week": 7,
     "This Month": 30,
-    "This Year": 365,
-    "All Time": 0,
   };
   const days = ranges[tab];
   if (days === 0) return "sort:stars";
@@ -517,8 +506,8 @@ export async function launchTrending(): Promise<void> {
       return;
     }
 
-    // Number keys 1-5 switch tabs
-    if (/^[1-5]$/.test(name)) {
+    // Number keys 1-3 switch tabs
+    if (/^[1-3]$/.test(name)) {
       switchTab(parseInt(name, 10) - 1);
       return;
     }
@@ -569,19 +558,6 @@ export async function launchTrending(): Promise<void> {
   loadTab(selectedTab);
 }
 
-// ── Utilities ─────────────────────────────────────────────────────────
-
-function openUrl(url: string): void {
-  try {
-    const p = process.platform;
-    if (p === "win32") Bun.spawn(["cmd", "/c", "start", "", url]);
-    else if (p === "darwin") Bun.spawn(["open", url]);
-    else Bun.spawn(["xdg-open", url]);
-  } catch {
-    // non-critical
-  }
-}
-
 // ── Auto-run ──────────────────────────────────────────────────────────
 if (import.meta.main) {
   launchTrending();