github-search-cli 0.6.0

package/src/history.ts

@@ -0,0 +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;
+  }
+}

package/src/init.ts

@@ -0,0 +1,47 @@
+/**
+ * `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("");
+}

package/src/normalizer.ts

@@ -0,0 +1,66 @@
+/**
+ * Result normalizer: convert a raw GitHub API item into our stable {@link Repo}
+ * shape. Keeping this isolated means a different provider (or a cached/offline
+ * source) only needs to produce the same `Repo` struct for the rest of the
+ * pipeline to work unchanged.
+ */
+import type { Repo } from "./types.ts";
+
+/** The subset of the GitHub "search repositories" item we care about. */
+export interface GitHubApiItem {
+  id: number;
+  name: string;
+  full_name: string;
+  owner?: { login?: string };
+  description: string | null;
+  html_url: string;
+  stargazers_count: number;
+  forks_count: number;
+  watchers_count: number;
+  language: string | null;
+  topics?: string[];
+  archived: boolean;
+  fork: boolean;
+  private: boolean;
+  created_at: string;
+  updated_at: string;
+  pushed_at: string;
+  score: number;
+}
+
+/** Raw GitHub search response envelope. */
+export interface GitHubSearchEnvelope {
+  total_count: number;
+  incomplete_results: boolean;
+  items: GitHubApiItem[];
+}
+
+/** 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] ?? "";
+  return {
+    id: item.id,
+    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,
+    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,
+  };
+}
+
+/** Normalize a full GitHub search envelope into {@link Repo} list. */
+export function normalizeEnvelope(env: GitHubSearchEnvelope): Repo[] {
+  return (env.items ?? []).map(normalizeRepo);
+}

package/src/notifications.ts

@@ -0,0 +1,69 @@
+/**
+ * Notification center — ephemeral alerts for rate limits, watch changes, etc.
+ * 
+ * ponytail: in-memory + last-session persistence. Skip 24h auto-clean.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { stateDir } from "./config.ts";
+
+export interface Notification {
+  id: number;
+  type: "info" | "warning" | "rate-limit" | "watch-change" | "upgrade";
+  icon: string;
+  message: string;
+  timestamp: number;
+}
+
+let nextId = 1;
+let notifs: Notification[] = [];
+const MAX_NOTIFS = 50;
+const FILE = join(stateDir(), "notifications.json");
+
+function load(): void {
+  try {
+    notifs = JSON.parse(readFileSync(FILE, "utf-8"));
+    nextId = (Math.max(...notifs.map((n) => n.id), 0) + 1);
+  } catch {
+    notifs = [];
+  }
+}
+
+function save(): void {
+  mkdirSync(stateDir(), { recursive: true });
+  writeFileSync(FILE, JSON.stringify(notifs));
+}
+
+export function addNotification(type: Notification["type"], message: string): Notification {
+  if (notifs.length === 0) load();
+  const n: Notification = { id: nextId++, type, icon: iconFor(type), message, timestamp: Date.now() };
+  notifs.unshift(n);
+  if (notifs.length > MAX_NOTIFS) notifs = notifs.slice(0, MAX_NOTIFS);
+  save();
+  return n;
+}
+
+function iconFor(type: Notification["type"]): string {
+  switch (type) {
+    case "info": return "ℹ";
+    case "warning": return "⚠";
+    case "rate-limit": return "🚫";
+    case "watch-change": return "🔔";
+    case "upgrade": return "📦";
+  }
+}
+
+export function getNotifications(): Notification[] {
+  if (notifs.length === 0) load();
+  return [...notifs];
+}
+
+export function dismissNotification(id: number): void {
+  notifs = notifs.filter((n) => n.id !== id);
+  save();
+}
+
+export function dismissAll(): void {
+  notifs = [];
+  save();
+}

package/src/output.ts

@@ -0,0 +1,74 @@
+/**
+ * Output layer: render ranked results either as machine-readable JSON or as a
+ * concise, human-readable list. This layer owns all presentation concerns so
+ * the search/ranking logic stays presentation-free.
+ */
+import type { Repo, SearchResponse } from "./types.ts";
+
+/** Format a number compactly (e.g. 1234 -> "1.2k"). */
+export function formatCount(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+  return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+
+/** Format an ISO date as YYYY-MM-DD. */
+export function formatDate(iso: string): string {
+  const d = new Date(iso);
+  if (isNaN(d.getTime())) return "unknown";
+  return d.toISOString().slice(0, 10);
+}
+
+/** Emit stable, parseable JSON. */
+export function renderJson(response: SearchResponse, rawQuery: string): string {
+  return JSON.stringify(
+    {
+      query: rawQuery,
+      totalCount: response.totalCount,
+      count: response.repos.length,
+      rateLimited: response.rateLimited,
+      results: response.repos,
+    },
+    null,
+    2,
+  );
+}
+
+/** Emit a concise, readable list for terminals. */
+export function renderHuman(response: SearchResponse, rawQuery: string): string {
+  const lines: string[] = [];
+  lines.push(`Query: ${rawQuery}`);
+  lines.push(`Matches: ${response.repos.length} (total available: ${response.totalCount})`);
+  if (response.rateLimited) {
+    lines.push("⚠ Rate limit hit — results may be incomplete. Set GITHUB_TOKEN to raise limits.");
+  }
+  lines.push("");
+
+  if (response.repos.length === 0) {
+    lines.push("No repositories found.");
+    return lines.join("\n");
+  }
+
+  response.repos.forEach((repo, i) => {
+    lines.push(renderRepo(i + 1, repo));
+    lines.push("");
+  });
+
+  return lines.join("\n").trimEnd();
+}
+
+function renderRepo(index: number, repo: Repo): string {
+  const lang = repo.language ?? "—";
+  const stars = formatCount(repo.stars);
+  const updated = formatDate(repo.updatedAt);
+  const tags: string[] = [];
+  if (repo.archived) tags.push("archived");
+  if (repo.isFork) tags.push("fork");
+  const tagStr = tags.length ? ` [${tags.join(", ")}]` : "";
+
+  const header = `${index}. ${repo.fullName}${tagStr}`;
+  const meta = `   ★ ${stars}  •  ${lang}  •  updated ${updated}`;
+  const desc = repo.description ? `   ${repo.description}` : "   (no description)";
+  const url = `   ${repo.url}`;
+  return [header, meta, desc, url].join("\n");
+}

package/src/pipe.ts

@@ -0,0 +1,65 @@
+/**
+ * Pipe-friendly format modifiers — output repo data as lines for shell piping.
+ */
+import type { Repo } from "./types.ts";
+
+export type FormatLine = "urls" | "names" | "ssh-urls" | "clone-commands" | "ids";
+
+/** Format repos as one URL per line. */
+export function formatUrls(repos: Repo[]): string {
+  return repos.map((r) => r.url).join("\n");
+}
+
+/** Format repos as one owner/repo per line. */
+export function formatNames(repos: Repo[]): string {
+  return repos.map((r) => r.fullName).join("\n");
+}
+
+/** Format repos as one git@github.com URL per line. */
+export function formatSshUrls(repos: Repo[]): string {
+  return repos.map((r) => `git@github.com:${r.fullName}.git`).join("\n");
+}
+
+/** Format repos as ready-to-paste git clone commands. */
+export function formatCloneCommands(repos: Repo[]): string {
+  return repos.map((r) => `git clone git@github.com:${r.fullName}.git`).join("\n");
+}
+
+/** Format repos as GitHub repo IDs, one per line. */
+export function formatIds(repos: Repo[]): string {
+  return repos.map((r) => String(r.id)).join("\n");
+}
+
+/** Format repos in the given line format. */
+export function formatLines(repos: Repo[], format: FormatLine): string {
+  switch (format) {
+    case "urls": return formatUrls(repos);
+    case "names": return formatNames(repos);
+    case "ssh-urls": return formatSshUrls(repos);
+    case "clone-commands": return formatCloneCommands(repos);
+    case "ids": return formatIds(repos);
+  }
+}
+
+/** Execute a pipe target (clone, open) on repos. */
+export async function pipeExec(repos: Repo[], target: string): Promise<void> {
+  for (const repo of repos) {
+    const url = repo.url;
+    switch (target) {
+      case "open":
+        await openUrl(url);
+        break;
+      case "clone":
+        console.log(`git clone git@github.com:${repo.fullName}.git`);
+        break;
+    }
+  }
+}
+
+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

@@ -0,0 +1,142 @@
+/**
+ * Search provider: talks to the GitHub REST search API.
+ *
+ * This is the only layer that performs network I/O. It implements the
+ * {@link SearchProvider} interface so alternative backends (a local index, a
+ * different forge, or an AI-powered source) can be swapped in without touching
+ * the CLI, query, ranking, or output layers.
+ */
+import type { ParsedQuery, SearchOptions, SearchProvider, SearchResponse } from "./types.ts";
+import { buildSearchUrl } from "./query.ts";
+import { normalizeEnvelope, type GitHubSearchEnvelope } from "./normalizer.ts";
+import { NetworkError, RateLimitError, ParseError } from "./errors.ts";
+import { MemoryCache } from "./cache.ts";
+
+/** A minimal logger so the CLI can surface outgoing queries, errors, and
+ *  rate-limit events without coupling to a specific logging framework. */
+export interface Logger {
+  debug(msg: string): void;
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+export class GitHubSearchProvider implements SearchProvider {
+  readonly name = "github";
+  private readonly logger: Logger;
+  private tokens: string[];
+  private tokenIndex = 0;
+  /** Shared cache across instances. */
+  static cache = new MemoryCache<SearchResponse>(300_000);
+
+  constructor(logger: Logger = noopLogger, tokens: string[] = []) {
+    this.logger = logger;
+    this.tokens = tokens.filter(Boolean);
+  }
+
+  private nextToken(): string | undefined {
+    if (this.tokens.length === 0) return undefined;
+    const token = this.tokens[this.tokenIndex % this.tokens.length];
+    this.tokenIndex++;
+    return token;
+  }
+
+  async search(query: ParsedQuery, options: SearchOptions): Promise<SearchResponse> {
+    // Check cache first
+    const cacheKey = MemoryCache.key(query.raw, options.sort, String(options.limit), String(options.page ?? 1));
+    const cached = GitHubSearchProvider.cache.get(cacheKey);
+    if (cached) {
+      this.logger.debug("[github] cache hit");
+      return cached;
+    }
+    this.logger.debug("[github] cache miss");
+    const url = buildSearchUrl(query, options);
+    this.logger.debug(`[github] outgoing query: ${query.raw}`);
+    this.logger.debug(`[github] request url: ${url}`);
+
+    const all: SearchResponse["repos"] = [];
+    let totalCount = 0;
+    let rateLimited = false;
+    let rateLimitRemaining: number | undefined;
+
+    // Fetch one page (or multiple pages to reach limit if page=1)
+    const perPage = Math.min(Math.max(options.limit, 1), 100);
+    const startPage = options.page ?? 1;
+    // ponytail: when page > 1, fetch only that specific page
+    const maxPages = startPage > 1 ? startPage : Math.ceil(options.limit / perPage);
+
+    for (let page = startPage > 1 ? startPage : 1; page <= maxPages; page++) {
+      const pagedUrl = appendPage(url, page, perPage);
+      let lastErr: Error | undefined;
+
+      // Try with current token; if 403, retry with next token
+      for (let attempt = 0; attempt <= this.tokens.length; attempt++) {
+        const token = this.tokens.length > 0 ? this.nextToken() : options.token;
+        try {
+          const res = await fetch(pagedUrl, {
+            headers: {
+              Accept: "application/vnd.github+json",
+              "X-GitHub-Api-Version": "2022-11-28",
+              "User-Agent": "search-cli",
+              ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            },
+          });
+
+          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;
+            }
+            this.logger.warn("[github] rate limit exceeded");
+            rateLimited = true;
+            throw new RateLimitError(!!token);
+          }
+          if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            this.logger.error(`[github] API error ${res.status}: ${body.slice(0, 200)}`);
+            throw new NetworkError();
+          }
+
+          const env = (await res.json()) as GitHubSearchEnvelope;
+          totalCount = env.total_count;
+          const repos = normalizeEnvelope(env);
+          all.push(...repos);
+          lastErr = undefined;
+          break; // success, exit token retry loop
+        } catch (err) {
+          lastErr = err as Error;
+          if (rateLimited) break;
+        }
+      }
+
+      if (lastErr && !rateLimited) throw lastErr;
+      if (rateLimited) break;
+      if (all.length >= options.limit) break;
+    }
+
+    const repos = all.slice(0, options.limit);
+    if (repos.length === 0) {
+      this.logger.debug("[github] empty results");
+    }
+    const response: SearchResponse = { totalCount, repos, rateLimited, rateLimitRemaining };
+    if (!rateLimited) {
+      GitHubSearchProvider.cache.set(cacheKey, response);
+    }
+    return response;
+  }
+}
+
+function appendPage(url: string, page: number, perPage: number): string {
+  const u = new URL(url);
+  u.searchParams.set("page", String(page));
+  u.searchParams.set("per_page", String(perPage));
+  return u.toString();
+}