github-search-cli 0.6.0

package/src/query.ts

@@ -0,0 +1,251 @@
+/**
+ * Query layer: parse a raw user query into structured qualifiers/keywords and
+ * build the GitHub search syntax string.
+ *
+ * This layer is deliberately free of any I/O. It only transforms strings into
+ * the {@link ParsedQuery} shape and then into a GitHub `q` parameter. Keeping it
+ * pure makes it trivially unit-testable and lets a future AI query-rewriter sit
+ * in front of it without side effects.
+ */
+import type { ParsedQuery, Qualifier, SearchOptions, SortStrategy } from "./types.ts";
+
+/** Qualifier keys we explicitly understand and can also accept as CLI flags. */
+export const KNOWN_QUALIFIERS = [
+  "language",
+  "stars",
+  "fork",
+  "archived",
+  "topic",
+  "user",
+  "org",
+  "repo",
+  "updated",
+  "pushed",
+  "visibility",
+  "in",
+  "size",
+  "license",
+  "created",
+] as const;
+
+export type KnownQualifier = (typeof KNOWN_QUALIFIERS)[number];
+
+/** Qualifier suggestions for Tab auto-complete. Maps a prefix to matching qualifiers. */
+export const QUALIFIER_SUGGESTIONS: Record<string, string[]> = {
+  l: ["language:"],
+  s: ["stars:", "size:"],
+  t: ["topic:"],
+  u: ["user:"],
+  o: ["org:"],
+  r: ["repo:"],
+  c: ["created:"],
+  p: ["pushed:"],
+  v: ["visibility:"],
+  i: ["in:"],
+  f: ["fork:"],
+  a: ["archived:"],
+};
+
+/** Find matching qualifier suggestions for a partial word. */
+export function suggestFor(input: string): string[] {
+  const trimmed = input.trim().toLowerCase();
+  if (trimmed.length === 0) return [];
+  // Single letter prefix
+  if (trimmed.length === 1 && QUALIFIER_SUGGESTIONS[trimmed]) {
+    return QUALIFIER_SUGGESTIONS[trimmed];
+  }
+  // Partial qualifier key (e.g. "lang" → "language:")
+  const matches = KNOWN_QUALIFIERS.filter(k => k.startsWith(trimmed));
+  return matches.map(k => k + ":");
+}
+
+/**
+ * Tokenize a raw query string while respecting double quotes so that phrases
+ * like `"machine learning"` or `repo:"my cool repo"` stay together as one
+ * token even when the quote is not at a token boundary.
+ */
+export function tokenize(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let inQuotes = false;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current += ch; // keep the quote so callers can detect quoted values
+    } else if (/\s/.test(ch) && !inQuotes) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+    } else {
+      current += ch;
+    }
+  }
+  if (current) {
+    // Strip quotes only when the whole token is wrapped in them
+    // (e.g. `"machine learning"`); leave `repo:"my repo"` intact for the
+    // qualifier parser to handle.
+    if (current.startsWith('"') && current.endsWith('"') && current.length >= 2) {
+      current = current.slice(1, -1);
+    }
+    tokens.push(current);
+  }
+  return tokens;
+}
+
+/**
+ * Parse a raw query string into a {@link ParsedQuery}.
+ *
+ * Rules:
+ *  - `key:value` or `key:"quoted value"` becomes a qualifier.
+ *  - `-key:value` becomes a negated qualifier.
+ *  - Anything else is a free-text keyword (quotes are stripped).
+ *  - The original string is preserved verbatim in `raw`.
+ */
+export function parseQuery(raw: string): ParsedQuery {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    return { keywords: [], qualifiers: [], raw };
+  }
+
+  const keywords: string[] = [];
+  const qualifiers: Qualifier[] = [];
+
+  for (const token of tokenize(trimmed)) {
+    const qualifier = matchQualifier(token);
+    if (qualifier) {
+      qualifiers.push(qualifier);
+    } else {
+      keywords.push(token);
+    }
+  }
+
+  return { keywords, qualifiers, raw: trimmed };
+}
+
+/** Match a single token against `[-]key:value` (value may be quoted). */
+function matchQualifier(token: string): Qualifier | null {
+  const negated = token.startsWith("-");
+  const body = negated ? token.slice(1) : token;
+  const idx = body.indexOf(":");
+  if (idx <= 0) return null; // no key, or starts with ':'
+  const key = body.slice(0, idx).toLowerCase();
+  let value = body.slice(idx + 1);
+  if (value === "") return null;
+  // A qualifier key must be a plain word (letters only) so that URLs like
+  // `http://example.com` are treated as free-text keywords, not qualifiers.
+  if (!/^[a-z]+$/i.test(key)) return null;
+  // A value starting with `//` is a URL scheme, not a qualifier value.
+  if (value.startsWith("//")) return null;
+  // Strip surrounding quotes from a quoted value (e.g. `repo:"my repo"`).
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    value = value.slice(1, -1);
+  }
+  return { key, value, negated };
+}
+
+/** CLI flag filters that map onto qualifiers. */
+export interface FlagFilters {
+  language?: string;
+  stars?: string;
+  org?: string;
+  user?: string;
+  topic?: string;
+  archived?: boolean;
+  fork?: boolean;
+}
+
+/**
+ * Merge flag-based filters into a parsed query. Flags are appended as
+ * qualifiers. Returns a new {@link ParsedQuery} (does not mutate the input).
+ */
+export function applyFlagFilters(
+  query: ParsedQuery,
+  flags: FlagFilters,
+): ParsedQuery {
+  const qualifiers = [...query.qualifiers];
+
+  if (flags.language) qualifiers.push({ key: "language", value: flags.language, negated: false });
+  if (flags.stars) qualifiers.push({ key: "stars", value: flags.stars, negated: false });
+  if (flags.org) qualifiers.push({ key: "org", value: flags.org, negated: false });
+  if (flags.user) qualifiers.push({ key: "user", value: flags.user, negated: false });
+  if (flags.topic) qualifiers.push({ key: "topic", value: flags.topic, negated: false });
+  if (flags.archived !== undefined)
+    qualifiers.push({ key: "archived", value: flags.archived ? "true" : "false", negated: false });
+  if (flags.fork !== undefined)
+    qualifiers.push({ key: "fork", value: flags.fork ? "true" : "false", negated: false });
+
+  return { ...query, qualifiers };
+}
+
+/**
+ * Validate a parsed query for conflicting or nonsensical filters.
+ * Throws an Error describing the first conflict found.
+ */
+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).");
+  }
+  if (has("visibility") && has("private")) {
+    throw new Error("Cannot combine `visibility:` and `private:` filters.");
+  }
+}
+
+/**
+ * Build the GitHub search `q` string from a parsed query.
+ * Keywords are joined with spaces; qualifiers are emitted as `key:value`
+ * (or `-key:value` when negated). Quoted values are re-quoted when they
+ * contain spaces.
+ */
+export function buildGitHubQuery(query: ParsedQuery): string {
+  const parts: string[] = [];
+
+  for (const kw of query.keywords) {
+    const alreadyQuoted = kw.startsWith('"') && kw.endsWith('"');
+    parts.push(kw.includes(" ") && !alreadyQuoted ? `"${kw}"` : kw);
+  }
+
+  for (const q of query.qualifiers) {
+    const needsQuote = q.value.includes(" ") && !q.value.startsWith('"');
+    const value = needsQuote ? `"${q.value}"` : q.value;
+    parts.push(`${q.negated ? "-" : ""}${q.key}:${value}`);
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Map our sort strategy to the GitHub `sort` param and the in-query `sort:`
+ * qualifier. GitHub's repository search supports `stars`, `forks`, `updated`
+ * and (implicitly) best-match. We encode best-match by omitting the param.
+ */
+export function githubSortParam(sort: SortStrategy): { sort?: string; order?: string } {
+  switch (sort) {
+    case "stars":
+      return { sort: "stars", order: "desc" };
+    case "forks":
+      return { sort: "forks", order: "desc" };
+    case "updated":
+      return { sort: "updated", order: "desc" };
+    case "best-match":
+    default:
+      return {}; // GitHub default relevance ranking
+  }
+}
+
+/** Build the full GitHub search URL for the given query + options. */
+export function buildSearchUrl(query: ParsedQuery, options: SearchOptions): string {
+  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) });
+  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

@@ -0,0 +1,55 @@
+/**
+ * Ranking layer: order normalized {@link Repo} results deterministically.
+ *
+ * All strategies are pure functions of the repo data plus a stable tie-breaker
+ * (repo id) so that identical inputs always produce identical output. A future
+ * AI reranker can be added as an additional strategy or as a post-step without
+ * changing the rest of the pipeline.
+ */
+import type { Repo, SortStrategy } from "./types.ts";
+
+/**
+ * Rank repos according to the chosen strategy.
+ * The sort is stable and deterministic: when two repos compare equal on the
+ * primary key, we fall back to descending stars, then descending id.
+ */
+export function rankRepos(repos: Repo[], strategy: SortStrategy): Repo[] {
+  const copy = [...repos];
+  switch (strategy) {
+    case "stars":
+      copy.sort(byKey((r) => r.stars));
+      break;
+    case "forks":
+      copy.sort(byKey((r) => r.forks));
+      break;
+    case "updated":
+      copy.sort(byKey((r) => Date.parse(r.updatedAt)));
+      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);
+      break;
+  }
+  return copy;
+}
+
+/** Comparator factory: descending by `key`, then descending stars, then
+ *  ascending id (stable, deterministic tie-break). */
+function byKey(key: (r: Repo) => number): (a: Repo, b: Repo) => number {
+  return (a, b) => key(b) - key(a) || b.stars - a.stars || a.id - b.id;
+}
+
+/**
+ * A simple, explainable composite score used for the (optional) "best" blend.
+ * Not used by default but available for an AI/rerank layer later.
+ * Range is roughly 0..1 after normalization by the caller.
+ */
+export function compositeScore(r: Repo): number {
+  // Log-scaled stars + recency bonus. Deterministic and transparent.
+  const starScore = Math.log10(r.stars + 1);
+  const recencyMs = Date.now() - Date.parse(r.pushedAt);
+  const recencyScore = Math.max(0, 1 - recencyMs / (1000 * 60 * 60 * 24 * 365));
+  return starScore * 0.7 + recencyScore * 0.3;
+}

package/src/saved-searches.ts

@@ -0,0 +1,58 @@
+/**
+ * Saved searches — named queries you can re-run anytime.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { SavedSearch, SortStrategy } from "./types.ts";
+import { stateDir } from "./config.ts";
+
+const SAVED_FILE = join(stateDir(), "saved-searches.json");
+
+function loadRaw(): SavedSearch[] {
+  mkdirSync(stateDir(), { recursive: true });
+  try {
+    return JSON.parse(readFileSync(SAVED_FILE, "utf-8")) as SavedSearch[];
+  } catch {
+    return [];
+  }
+}
+
+function saveRaw(searches: SavedSearch[]): void {
+  mkdirSync(stateDir(), { recursive: true });
+  writeFileSync(SAVED_FILE, JSON.stringify(searches, null, 2));
+}
+
+/** Get all saved searches, sorted by last run time (most recent first). */
+export function getSavedSearches(): SavedSearch[] {
+  return loadRaw().sort((a, b) => (b.lastRunAt ?? b.createdAt) - (a.lastRunAt ?? a.createdAt));
+}
+
+/** Save a new search. Overwrites if name already exists. */
+export function saveSearch(name: string, query: string, mode: "search" | "trending", sort: SortStrategy, limit: number, tab?: string): SavedSearch {
+  const searches = loadRaw();
+  const now = Date.now();
+  const existing = searches.findIndex((s) => s.name === name);
+  const entry: SavedSearch = { name, query, mode, sort, limit, tab, createdAt: now, lastRunAt: now };
+  if (existing >= 0) {
+    searches[existing] = { ...searches[existing], ...entry, createdAt: searches[existing].createdAt };
+  } else {
+    searches.push(entry);
+  }
+  saveRaw(searches);
+  return entry;
+}
+
+/** Delete a saved search by name. */
+export function deleteSavedSearch(name: string): void {
+  saveRaw(loadRaw().filter((s) => s.name !== name));
+}
+
+/** Update lastRunAt for a saved search. */
+export function touchSavedSearch(name: string): void {
+  const searches = loadRaw();
+  const found = searches.find((s) => s.name === name);
+  if (found) {
+    found.lastRunAt = Date.now();
+    saveRaw(searches);
+  }
+}

package/src/session.ts

@@ -0,0 +1,35 @@
+/**
+ * Session restore — save/restore UI state between restarts.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { SessionState, SortStrategy } from "./types.ts";
+import { stateDir } from "./config.ts";
+
+const SESSION_FILE = join(stateDir(), "session.json");
+
+export function saveSession(state: SessionState): void {
+  mkdirSync(stateDir(), { recursive: true });
+  try {
+    writeFileSync(SESSION_FILE, JSON.stringify(state));
+  } catch {
+    // non-critical
+  }
+}
+
+export function restoreSession(): SessionState | null {
+  try {
+    const raw = readFileSync(SESSION_FILE, "utf-8");
+    return JSON.parse(raw) as SessionState;
+  } catch {
+    return null;
+  }
+}
+
+export function clearSession(): void {
+  try {
+    writeFileSync(SESSION_FILE, "");
+  } catch {
+    // non-critical
+  }
+}

package/src/share.ts

@@ -0,0 +1,49 @@
+/**
+ * Share repo — copy formatted snippets to clipboard.
+ */
+import type { Repo } from "./types.ts";
+
+export type ShareFormat = "markdown" | "plain" | "gh-cli" | "short";
+
+export function formatShare(repo: Repo, format: ShareFormat): string {
+  switch (format) {
+    case "markdown":
+      return `[${repo.fullName}](${repo.url}) — ${repo.description ?? ""}`.trim();
+    case "plain":
+      return `${repo.fullName} — ${repo.description ?? ""} — ${repo.url}`.trim();
+    case "gh-cli":
+      return `gh repo view ${repo.fullName}`;
+    case "short":
+      return repo.fullName;
+  }
+}
+
+/** Copy text to clipboard via platform command. */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    const p = process.platform;
+    if (p === "win32") {
+      const proc = Bun.spawn(["clip"], { stdin: "pipe" });
+      proc.stdin.write(text);
+      proc.stdin.end();
+      await proc.exited;
+    } else if (p === "darwin") {
+      const proc = Bun.spawn(["pbcopy"], { stdin: "pipe" });
+      proc.stdin.write(text);
+      proc.stdin.end();
+      await proc.exited;
+    } else {
+      // Linux — try xclip, then wl-copy
+      const cmd = Bun.which("xclip") ? ["xclip", "-selection", "clipboard"] :
+        Bun.which("wl-copy") ? ["wl-copy"] : null;
+      if (!cmd) return false;
+      const proc = Bun.spawn(cmd, { stdin: "pipe" });
+      proc.stdin.write(text);
+      proc.stdin.end();
+      await proc.exited;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/status.ts

@@ -0,0 +1,61 @@
+/**
+ * Status bar state machine with spinner animation.
+ */
+export type StatusType = "idle" | "searching" | "loading" | "success" | "error";
+
+const SEARCH_SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const LOADING_SPINNER = ["▰▱▱▱▱", "▰▰▱▱▱", "▰▰▰▱▱", "▰▰▰▰▱", "▰▰▰▰▰"];
+
+export class StatusManager {
+  private spinnerInterval: ReturnType<typeof setInterval> | null = null;
+  private spinnerIndex = 0;
+  private type: StatusType = "idle";
+  private message = "";
+  private onUpdate: (text: string) => void;
+
+  constructor(onUpdate: (text: string) => void) {
+    this.onUpdate = onUpdate;
+  }
+
+  set(type: StatusType, message: string): void {
+    this.stopSpinner();
+    this.type = type;
+    this.message = message;
+
+    if (type === "searching" || type === "loading") {
+      this.startSpinner(type === "searching" ? SEARCH_SPINNER : LOADING_SPINNER);
+    } else {
+      this.emit();
+    }
+  }
+
+  private startSpinner(frames: string[]): void {
+    this.spinnerIndex = 0;
+    this.emit(frames[0]);
+    this.spinnerInterval = setInterval(() => {
+      this.spinnerIndex = (this.spinnerIndex + 1) % frames.length;
+      this.emit(frames[this.spinnerIndex]);
+    }, 120);
+  }
+
+  private stopSpinner(): void {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+      this.spinnerInterval = null;
+    }
+  }
+
+  private emit(spinner?: string): void {
+    const icon = this.type === "searching" ? "🔍"
+      : this.type === "loading" ? "📦"
+      : this.type === "success" ? "✓"
+      : this.type === "error" ? "⚠"
+      : " ";
+    const prefix = spinner ?? "";
+    this.onUpdate(`${icon} ${this.message}  ${prefix}`.trim());
+  }
+
+  dispose(): void {
+    this.stopSpinner();
+  }
+}

package/src/themes.ts

@@ -0,0 +1,52 @@
+/**
+ * Theme system — 3 built-in palettes. Apply theme to TUI colors.
+ */
+export interface Theme {
+  name: string;
+  bg: string;
+  surface: string;
+  text: string;
+  muted: string;
+  blue: string;
+  green: string;
+  yellow: string;
+  red: string;
+  teal: string;
+  purple: string;
+  orange: string;
+  border: string;
+  selectionBg: string;
+  selectionText: string;
+}
+
+const THEMES: Record<string, Theme> = {
+  "tokyo-night": {
+    name: "tokyo-night",
+    bg: "#1e1e2e", surface: "#181825", text: "#cdd6f4", muted: "#6c7086",
+    blue: "#89b4fa", green: "#a6e3a1", yellow: "#f9e2af", red: "#f38ba8",
+    teal: "#94e2d5", purple: "#cba6f7", orange: "#fab387",
+    border: "#45475a", selectionBg: "#2d5bcf", selectionText: "#ffffff",
+  },
+  dracula: {
+    name: "dracula",
+    bg: "#282a36", surface: "#21222c", text: "#f8f8f2", muted: "#6272a4",
+    blue: "#8be9fd", green: "#50fa7b", yellow: "#f1fa8c", red: "#ff5555",
+    teal: "#50fa7b", purple: "#bd93f9", orange: "#ffb86c",
+    border: "#44475a", selectionBg: "#bd93f9", selectionText: "#282a36",
+  },
+  monokai: {
+    name: "monokai",
+    bg: "#272822", surface: "#1e1f1c", text: "#f8f8f2", muted: "#75715e",
+    blue: "#66d9ef", green: "#a6e22e", yellow: "#e6db74", red: "#f92672",
+    teal: "#a6e22e", purple: "#ae81ff", orange: "#fd971f",
+    border: "#49483e", selectionBg: "#e6db74", selectionText: "#272822",
+  },
+};
+
+export function loadTheme(name: string): Theme {
+  return THEMES[name] ?? THEMES["tokyo-night"];
+}
+
+export function listThemes(): string[] {
+  return Object.keys(THEMES);
+}

package/src/tips.ts

@@ -0,0 +1,27 @@
+/**
+ * Startup tips — rotate through helpful hints.
+ */
+const TIPS = [
+  "💡 Tip: Press ? to see all keyboard shortcuts",
+  "💡 Tip: Use Ctrl+R to recall past searches",
+  "💡 Tip: Press b to bookmark a repository",
+  "💡 Tip: Tab auto-completes qualifiers like language: and stars:",
+  "💡 Tip: Press Ctrl+E to export results as CSV or Markdown",
+  "💡 Tip: Set GITHUB_TOKEN for higher API rate limits",
+  "💡 Tip: Press c to compare up to 5 repos side-by-side",
+  "💡 Tip: Press d for a deep-dive into any repo",
+  "💡 Tip: Press E to browse popular GitHub topics",
+  "💡 Tip: Press Ctrl+P to copy a repo link to clipboard",
+];
+
+let lastIndex = -1;
+
+/** Get the next tip (never repeats the same tip twice in a row). */
+export function nextTip(): string {
+  let idx: number;
+  do {
+    idx = Math.floor(Math.random() * TIPS.length);
+  } while (idx === lastIndex && TIPS.length > 1);
+  lastIndex = idx;
+  return TIPS[idx];
+}