github-search-cli 0.6.1 → 0.8.0

package/src/explore.ts

@@ -1,45 +1,29 @@
-/**
- * Topic explorer — browse popular GitHub topics.
- * 
- * ponytail: fetch flat topic list, no hierarchy. Selecting a topic
- * triggers a search. Hierarchy adds ~60 lines for marginal benefit.
- */
-import { ParseError } from "./errors.ts";
-
-export interface TopicItem {
-  name: string;
-  description: string;
-  repoCount: number;
-}
-
-/** Fetch popular topics from github.com/topics. */
-export async function fetchTopics(): Promise<TopicItem[]> {
-  const res = await fetch("https://github.com/topics", {
-    headers: { "User-Agent": "search-cli/1.0" },
-  });
-  if (!res.ok) throw new ParseError("GitHub topics", `HTTP ${res.status}`);
-  const html = await res.text();
-
-  const topics: TopicItem[] = [];
-  // Parse topic cards from the HTML
-  const cards = html.split('<article class="border');
-  for (let i = 1; i < cards.length; i++) {
-    const block = cards[i];
-
-    const nameMatch = block.match(/href="\/topics\/([^"]+)"/);
-    if (!nameMatch) continue;
-    const name = decodeURIComponent(nameMatch[1]);
-
-    const descMatch = block.match(/<p[^>]*>([\s\S]*?)<\/p>/);
-    const description = descMatch
-      ? descMatch[1].replace(/<[^>]*>/g, "").replace(/\s+/g, " ").trim()
-      : "";
-
-    const countMatch = block.match(/([\d,]+)\s+repositories/);
-    const repoCount = countMatch ? parseInt(countMatch[1].replace(/,/g, "")) : 0;
-
-    topics.push({ name, description, repoCount });
-  }
-
-  return topics.slice(0, 30);
-}
+/**
+ * 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,56 +1,63 @@
-/**
- * Export — format repos as JSON, CSV, Markdown, or plain text.
- */
-import { writeFileSync } from "fs";
-import type { Repo } from "./types.ts";
-
-export type ExportFormat = "json" | "csv" | "markdown" | "text";
-
-/** Format repos as JSON string. */
-export function formatJson(repos: Repo[]): string {
-  return JSON.stringify(repos, null, 2);
-}
-
-/** 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},"${r.fullName}",${r.stars},${r.forks},"${r.language ?? ""}","${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 = `./search-cli-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,46 +1,112 @@
-/**
- * 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. */
+
+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", 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: "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: " 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" },
+      ],
+      note: "Also: Open, History, Export, Share, Topics, Saved, Notifs, Help",
+    },
+    {
+      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, bookmarks, saved)" },
+        { keys: "↑ ↓ / j k", action: "Navigate overlay list" },
+      ],
+    },
+    {
+      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/history.ts

@@ -1,91 +1,91 @@
-/**
- * Persistent search history — append-only JSONL with rotation.
- */
-import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, unlinkSync } from "fs";
-import { join } from "path";
-import type { HistoryEntry } from "./types.ts";
-import { stateDir } from "./config.ts";
-
-const HISTORY_FILE = join(stateDir(), "history.jsonl");
-const MAX_ENTRIES = 500;
-
-function ensureDir() {
-  mkdirSync(stateDir(), { recursive: true });
-}
-
-/** Append one entry to the history log. */
-export function appendHistory(entry: HistoryEntry): void {
-  ensureDir();
-  const line = JSON.stringify(entry) + "\n";
-  try {
-    appendFileSync(HISTORY_FILE, line, "utf-8");
-  } catch {
-    // non-critical
-  }
-}
-
-/** Read all history entries, newest first, deduplicating consecutive identical queries. */
-export function readHistory(): HistoryEntry[] {
-  try {
-    const raw = readFileSync(HISTORY_FILE, "utf-8").trim();
-    if (!raw) return [];
-    const lines = raw.split("\n").filter(Boolean);
-    const entries: HistoryEntry[] = lines.map((l) => JSON.parse(l) as HistoryEntry);
-
-    // Sorted oldest-first in file; reverse to newest-first
-    entries.reverse();
-
-    // Deduplicate consecutive identical queries (keep newest)
-    const deduped: HistoryEntry[] = [];
-    let lastQuery: string | undefined;
-    for (const e of entries) {
-      if (e.query !== lastQuery) {
-        deduped.push(e);
-        lastQuery = e.query;
-      }
-    }
-    return deduped;
-  } catch {
-    return [];
-  }
-}
-
-/** Delete a single history entry by index (0 = newest). */
-export function deleteHistoryEntry(index: number): void {
-  const entries = readHistory();
-  if (index < 0 || index >= entries.length) return;
-  const removed = entries[index];
-  // Rewrite file without the removed entry
-  const remaining = entries.filter((e) => e.timestamp !== removed.timestamp || e.query !== removed.query);
-  ensureDir();
-  // Reverse back to oldest-first for file order
-  writeFileSync(HISTORY_FILE, remaining.reverse().map((e) => JSON.stringify(e)).join("\n") + "\n");
-}
-
-/** Clear all history. */
-export function clearHistory(): void {
-  try {
-    writeFileSync(HISTORY_FILE, "");
-  } catch {
-    // non-critical
-  }
-}
-
-/** Rotate history to max entries (trim oldest). */
-export function rotateHistory(): void {
-  const entries = readHistory();
-  if (entries.length <= MAX_ENTRIES) return;
-  const trimmed = entries.slice(0, MAX_ENTRIES);
-  ensureDir();
-  writeFileSync(HISTORY_FILE, trimmed.reverse().map((e) => JSON.stringify(e)).join("\n") + "\n");
-}
-
-/** Count entries in history file. */
-export function historyCount(): number {
-  try {
-    const raw = readFileSync(HISTORY_FILE, "utf-8").trim();
-    return raw ? raw.split("\n").length : 0;
-  } catch {
-    return 0;
-  }
-}
+/**
+ * Persistent search history — append-only JSONL with rotation.
+ */
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, unlinkSync } from "fs";
+import { join } from "path";
+import type { HistoryEntry } from "./types";
+import { stateDir } from "./config";
+
+const HISTORY_FILE = join(stateDir(), "history.jsonl");
+const MAX_ENTRIES = 500;
+
+function ensureDir() {
+  mkdirSync(stateDir(), { recursive: true });
+}
+
+/** Append one entry to the history log. */
+export function appendHistory(entry: HistoryEntry): void {
+  ensureDir();
+  const line = JSON.stringify(entry) + "\n";
+  try {
+    appendFileSync(HISTORY_FILE, line, "utf-8");
+  } catch {
+    // non-critical
+  }
+}
+
+/** Read all history entries, newest first, deduplicating consecutive identical queries. */
+export function readHistory(): HistoryEntry[] {
+  try {
+    const raw = readFileSync(HISTORY_FILE, "utf-8").trim();
+    if (!raw) return [];
+    const lines = raw.split("\n").filter(Boolean);
+    const entries: HistoryEntry[] = lines.map((l) => JSON.parse(l) as HistoryEntry);
+
+    // Sorted oldest-first in file; reverse to newest-first
+    entries.reverse();
+
+    // Deduplicate consecutive identical queries (keep newest)
+    const deduped: HistoryEntry[] = [];
+    let lastQuery: string | undefined;
+    for (const e of entries) {
+      if (e.query !== lastQuery) {
+        deduped.push(e);
+        lastQuery = e.query;
+      }
+    }
+    return deduped;
+  } catch {
+    return [];
+  }
+}
+
+/** Delete a single history entry by index (0 = newest). */
+export function deleteHistoryEntry(index: number): void {
+  const entries = readHistory();
+  if (index < 0 || index >= entries.length) return;
+  const removed = entries[index];
+  // Rewrite file without the removed entry
+  const remaining = entries.filter((e) => e.timestamp !== removed.timestamp || e.query !== removed.query);
+  ensureDir();
+  // Reverse back to oldest-first for file order
+  writeFileSync(HISTORY_FILE, remaining.reverse().map((e) => JSON.stringify(e)).join("\n") + "\n");
+}
+
+/** Clear all history. */
+export function clearHistory(): void {
+  try {
+    writeFileSync(HISTORY_FILE, "");
+  } catch {
+    // non-critical
+  }
+}
+
+/** Rotate history to max entries (trim oldest). */
+export function rotateHistory(): void {
+  const entries = readHistory();
+  if (entries.length <= MAX_ENTRIES) return;
+  const trimmed = entries.slice(0, MAX_ENTRIES);
+  ensureDir();
+  writeFileSync(HISTORY_FILE, trimmed.reverse().map((e) => JSON.stringify(e)).join("\n") + "\n");
+}
+
+/** Count entries in history file. */
+export function historyCount(): number {
+  try {
+    const raw = readFileSync(HISTORY_FILE, "utf-8").trim();
+    return raw ? raw.split("\n").length : 0;
+  } catch {
+    return 0;
+  }
+}

package/src/init.ts

@@ -1,47 +1,55 @@
-/**
- * `search-cli init` wizard — interactive one-time config setup.
- * 
- * ponytail: simple stdin prompts, no curses/readline UI.
- */
-import { createInterface } from "readline";
-import { saveConfig } from "./config.ts";
-import type { Config, SortStrategy } from "./types.ts";
-
-function ask(query: string): Promise<string> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(query, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}
-
-export async function runInitWizard(): Promise<void> {
-  console.log("");
-  console.log("  search-cli setup wizard");
-  console.log("  ──────────────────────");
-  console.log("");
-
-  const token = await ask("  GitHub token (optional, press Enter to skip): ");
-  const sortStr = await ask("  Default sort [best-match/stars/updated/forks] (best-match): ");
-  const limitStr = await ask("  Default result limit [10-100] (50): ");
-
-  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",
-    cacheTtlSeconds: 300,
-    defaultTab: "search",
-  };
-
-  if (token) config.githubToken = token;
-
-  saveConfig(config);
-  const { configPath } = await import("./config.ts");
-  console.log(`  ✓ Config saved to ${configPath()}`);
-  console.log("  Run 'search-cli' to start browsing!");
-  console.log("");
-}
+/**
+ * `ghfind init` wizard — interactive one-time config setup.
+ * 
+ * ponytail: simple stdin prompts, no curses/readline UI.
+ */
+import { createInterface } from "readline";
+import { saveConfig } from "./config";
+import { listThemes } from "./themes";
+import type { Config, SortStrategy } from "./types";
+
+function ask(query: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function runInitWizard(): Promise<void> {
+  console.log("");
+  console.log("  ghfind setup wizard");
+  console.log("  ──────────────────────");
+  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: themes.includes(themeStr) ? themeStr : "tokyo-night",
+    cacheTtlSeconds: 300,
+    defaultTab: "search",
+  };
+
+  if (token) config.githubToken = token;
+
+  saveConfig(config);
+  const { configPath } = await import("./config.ts");
+  console.log(`  ✓ Config saved to ${configPath()}`);
+  console.log("  Run 'ghfind' to start browsing!");
+  console.log("");
+}