github-search-cli 0.7.0 → 0.8.1

package/src/types.ts

@@ -1,12 +1,4 @@
-/**
- * Core domain types shared across the CLI.
- *
- * The architecture is intentionally split into layers:
- *   CLI -> QueryBuilder -> SearchProvider -> Normalizer -> Ranking -> Output
- * Each layer depends only on the types defined here, so an AI layer can be
- * slotted in later (e.g. a query rewriter before QueryBuilder, or a reranker
- * after Ranking) without touching the rest of the code.
- */
+/** Core domain types shared across the CLI. */
 
 /** A single parsed search qualifier (e.g. `language:Rust`). */
 export interface Qualifier {
@@ -126,7 +118,7 @@ export interface CacheEntry<T> {
   ttlMs: number;
 }
 
-/** Application config, persisted to ~/.config/search-cli/config.json. */
+/** Application config, persisted to ~/.config/ghfind/config.json. */
 export interface Config {
   githubToken?: string;
   githubTokens?: string[];
@@ -140,7 +132,7 @@ export interface Config {
   bookmarkFile?: string;
 }
 
-/** Abstract search provider. New sources (GitLab, local index, AI, ...) can
+/** Abstract search provider. New sources (GitLab, local index, etc.) can
  *  implement this interface without changing any other layer. */
 export interface SearchProvider {
   readonly name: string;

package/src/watch.ts

@@ -1,12 +1,9 @@
 /**
  * Watch mode — periodically re-run a search and show changes.
  * 
- * ponytail: simple poll + diff. No notifications (P4 cross-ref).
  */
-import type { ParsedQuery, SearchOptions, Repo } from "./types.ts";
-import { GitHubSearchProvider } from "./provider.ts";
-import { parseQuery, applyFlagFilters } from "./query.ts";
-import { rankRepos } from "./ranking.ts";
+import type { ParsedQuery, SearchOptions, Repo } from "./types";
+import { parseQuery, applyFlagFilters, rankRepos, createGitHubSearch } from "./search";
 
 export interface WatchOptions {
   query: string;
@@ -32,7 +29,7 @@ export async function runWatch(
   const tick = async () => {
     try {
       const parsed = applyFlagFilters(parseQuery(opts.query), {});
-      const provider = new GitHubSearchProvider(undefined, opts.token ? [opts.token] : []);
+      const provider = createGitHubSearch(undefined, opts.token ? [opts.token] : []);
       const options: SearchOptions = {
         limit: opts.limit,
         sort: opts.sort,

package/bin/search-cli.js

@@ -1,17 +0,0 @@
-#!/usr/bin/env bun
-/**
- * search-cli — npm bin entry point.
- * Requires Bun (https://bun.sh) to run.
- */
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const cli = join(__dirname, "..", "src", "cli.ts");
-
-try {
-  await import(cli);
-} catch (err) {
-  console.error("Failed to start search-cli. Is Bun installed? (https://bun.sh)");
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
-}

package/completions/search-cli.fish

@@ -1,19 +0,0 @@
-# search-cli fish completion
-# Source: source <(search-cli --completion fish)
-
-complete -c search-cli -l json -d "JSON output"
-complete -c search-cli -l csv -d "CSV output"
-complete -c search-cli -l markdown -d "Markdown table output"
-complete -c search-cli -l count -d "Only result count"
-complete -c search-cli -l limit -d "Max results" -r
-complete -c search-cli -l sort -d "Sort strategy" -r -f -a "best-match stars updated forks"
-complete -c search-cli -l token -d "GitHub token" -r
-complete -c search-cli -l trending -d "Trending mode"
-complete -c search-cli -l since -d "Trending period" -r -f -a "daily weekly monthly"
-complete -c search-cli -l pipe -d "Pipe target" -r -f -a "clone open"
-complete -c search-cli -l format -d "Output format" -r -f -a "urls names ssh-urls clone-commands ids"
-complete -c search-cli -l watch -d "Watch mode"
-complete -c search-cli -l interval -d "Watch interval seconds" -r
-complete -c search-cli -l version -d "Print version"
-complete -c search-cli -l help -d "Print help"
-complete -c search-cli -l completion -d "Shell" -r -f -a "bash zsh fish"

package/src/cache.ts

@@ -1,64 +0,0 @@
-/**
- * In-memory LRU cache with TTL for API responses.
- * 
- * ponytail: in-memory only. Disk cache adds ~70 lines for marginal benefit
- * (re-cache on restart rather than re-fetch). Add disk layer if cache-miss
- * rate after restart becomes a problem.
- */
-import type { CacheEntry } from "./types.ts";
-
-const MAX_SIZE = 50;
-
-export class MemoryCache<T> {
-  private cache = new Map<string, CacheEntry<T>>();
-
-  constructor(private defaultTtlMs: number = 300_000) {}
-
-  /** Build a normalized cache key. */
-  static key(...parts: string[]): string {
-    return parts.join("::").toLowerCase().replace(/\s+/g, " ");
-  }
-
-  /** Get entry if not expired. Returns null on miss or expiry. */
-  get(key: string): T | null {
-    const entry = this.cache.get(key);
-    if (!entry) return null;
-    if (Date.now() - entry.cachedAt > entry.ttlMs) {
-      this.cache.delete(key);
-      return null;
-    }
-    // Move to most-recently-used position
-    this.cache.delete(key);
-    this.cache.set(key, entry);
-    return entry.data;
-  }
-
-  /** Set entry with optional per-entry TTL. */
-  set(key: string, data: T, ttlMs?: number): void {
-    if (this.cache.size >= MAX_SIZE) {
-      // Evict least-recently-used (first inserted key)
-      const firstKey = this.cache.keys().next().value;
-      if (firstKey !== undefined) this.cache.delete(firstKey);
-    }
-    this.cache.set(key, {
-      data,
-      cachedAt: Date.now(),
-      ttlMs: ttlMs ?? this.defaultTtlMs,
-    });
-  }
-
-  /** Remove entry. */
-  delete(key: string): void {
-    this.cache.delete(key);
-  }
-
-  /** Clear all entries. */
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /** Number of entries in cache. */
-  get size(): number {
-    return this.cache.size;
-  }
-}

package/src/normalizer.ts

@@ -1,66 +0,0 @@
-/**
- * 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 ?? 0,
-    fullName: item.full_name ?? "",
-    name: item.name ?? "",
-    owner,
-    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 ?? 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,
-  };
-}
-
-/** Normalize a full GitHub search envelope into {@link Repo} list. */
-export function normalizeEnvelope(env: GitHubSearchEnvelope): Repo[] {
-  return (env.items ?? []).map(normalizeRepo);
-}

package/src/provider.ts

@@ -1,165 +0,0 @@
-/**
- * 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}` } : {}),
-            },
-          });
-
-          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);
-            }
-            // 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(() => "");
-            this.logger.error(`[github] API error ${res.status}: ${body.slice(0, 200)}`);
-            throw new NetworkError();
-          }
-
-          // 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);
-          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();
-}

package/src/query.ts

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