github-search-cli 0.6.1 → 0.8.0

package/src/types.ts

@@ -1,148 +1,140 @@
-/**
- * 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.
- */
-
-/** A single parsed search qualifier (e.g. `language:Rust`). */
-export interface Qualifier {
-  /** The qualifier key, e.g. "language", "stars", "topic". */
-  key: string;
-  /** The qualifier value, e.g. "Rust", ">100". */
-  value: string;
-  /** True when the qualifier was negated (e.g. `-language:Rust`). */
-  negated: boolean;
-}
-
-/** The fully parsed, normalized representation of a user's search request. */
-export interface ParsedQuery {
-  /** Free-text keywords (everything that is not a qualifier). */
-  keywords: string[];
-  /** Structured qualifiers extracted from the query string. */
-  qualifiers: Qualifier[];
-  /** The original, untouched query string (preserved for debugging/display). */
-  raw: string;
-}
-
-/** A repository as returned by a search provider, normalized to a stable shape. */
-export interface Repo {
-  id: number;
-  fullName: string; // owner/name
-  name: string;
-  owner: string;
-  description: string | null;
-  url: string;
-  stars: number;
-  forks: number;
-  watchers: number;
-  language: string | null;
-  topics: string[];
-  archived: boolean;
-  isFork: boolean;
-  private: boolean;
-  createdAt: string; // ISO timestamp
-  updatedAt: string; // ISO timestamp
-  pushedAt: string; // ISO timestamp
-  score: number; // relevance score returned by GitHub
-}
-
-/** Ranking strategies supported by the ranking layer. */
-export type SortStrategy = "best-match" | "stars" | "updated" | "forks";
-
-/** Options that control how a search is executed and presented. */
-export interface SearchOptions {
-  /** Maximum number of results to return (pagination stops at this limit). */
-  limit: number;
-  /** Ranking strategy. */
-  sort: SortStrategy;
-  /** Emit machine-readable JSON instead of human-readable text. */
-  json: boolean;
-  /** GitHub API token (optional, raises rate limits). */
-  token?: string;
-  /** Page number for pagination (1-based, default 1). */
-  page?: number;
-  /** Verbose logging (outgoing query, errors, rate limits). */
-  verbose: boolean;
-}
-
-/** A paginated response from a search provider. */
-export interface SearchResponse {
-  totalCount: number;
-  repos: Repo[];
-  /** True when the provider hit a rate limit. */
-  rateLimited: boolean;
-  /** Remaining requests in the current rate-limit window, if known. */
-  rateLimitRemaining?: number;
-}
-
-// ─── P1: Memory types ───────────────────────────────────────────────
-
-/** A single history entry (append-only log). */
-export interface HistoryEntry {
-  query: string;
-  mode: "search" | "trending";
-  tab?: string;
-  timestamp: number;
-  resultCount: number;
-}
-
-/** A saved bookmark entry. */
-export interface Bookmark {
-  repo: Repo;
-  savedAt: number;
-  tags: string[];
-  notes?: string;
-}
-
-/** A named, saved search. */
-export interface SavedSearch {
-  name: string;
-  query: string;
-  mode: "search" | "trending";
-  tab?: string;
-  sort: SortStrategy;
-  limit: number;
-  createdAt: number;
-  lastRunAt?: number;
-}
-
-/** Session state restored on startup. */
-export interface SessionState {
-  mode: "search" | "trending";
-  query: string;
-  sort: SortStrategy;
-  limit: number;
-  trendingTab: string;
-}
-
-/** Cache entry with TTL. */
-export interface CacheEntry<T> {
-  data: T;
-  cachedAt: number;
-  ttlMs: number;
-}
-
-/** Application config, persisted to ~/.config/search-cli/config.json. */
-export interface Config {
-  githubToken?: string;
-  githubTokens?: string[];
-  defaultSort: SortStrategy;
-  defaultLimit: number;
-  language?: string;
-  theme: string;
-  cacheTtlSeconds: number;
-  defaultTab: "search" | "trending";
-  historySize?: number;
-  bookmarkFile?: string;
-}
-
-/** Abstract search provider. New sources (GitLab, local index, AI, ...) can
- *  implement this interface without changing any other layer. */
-export interface SearchProvider {
-  readonly name: string;
-  search(query: ParsedQuery, options: SearchOptions): Promise<SearchResponse>;
+/** Core domain types shared across the CLI. */
+
+/** A single parsed search qualifier (e.g. `language:Rust`). */
+export interface Qualifier {
+  /** The qualifier key, e.g. "language", "stars", "topic". */
+  key: string;
+  /** The qualifier value, e.g. "Rust", ">100". */
+  value: string;
+  /** True when the qualifier was negated (e.g. `-language:Rust`). */
+  negated: boolean;
+}
+
+/** The fully parsed, normalized representation of a user's search request. */
+export interface ParsedQuery {
+  /** Free-text keywords (everything that is not a qualifier). */
+  keywords: string[];
+  /** Structured qualifiers extracted from the query string. */
+  qualifiers: Qualifier[];
+  /** The original, untouched query string (preserved for debugging/display). */
+  raw: string;
+}
+
+/** A repository as returned by a search provider, normalized to a stable shape. */
+export interface Repo {
+  id: number;
+  fullName: string; // owner/name
+  name: string;
+  owner: string;
+  description: string | null;
+  url: string;
+  stars: number;
+  forks: number;
+  watchers: number;
+  language: string | null;
+  topics: string[];
+  archived: boolean;
+  isFork: boolean;
+  private: boolean;
+  createdAt: string; // ISO timestamp
+  updatedAt: string; // ISO timestamp
+  pushedAt: string; // ISO timestamp
+  score: number; // relevance score returned by GitHub
+}
+
+/** Ranking strategies supported by the ranking layer. */
+export type SortStrategy = "best-match" | "stars" | "updated" | "forks";
+
+/** Options that control how a search is executed and presented. */
+export interface SearchOptions {
+  /** Maximum number of results to return (pagination stops at this limit). */
+  limit: number;
+  /** Ranking strategy. */
+  sort: SortStrategy;
+  /** Emit machine-readable JSON instead of human-readable text. */
+  json: boolean;
+  /** GitHub API token (optional, raises rate limits). */
+  token?: string;
+  /** Page number for pagination (1-based, default 1). */
+  page?: number;
+  /** Verbose logging (outgoing query, errors, rate limits). */
+  verbose: boolean;
+}
+
+/** A paginated response from a search provider. */
+export interface SearchResponse {
+  totalCount: number;
+  repos: Repo[];
+  /** True when the provider hit a rate limit. */
+  rateLimited: boolean;
+  /** Remaining requests in the current rate-limit window, if known. */
+  rateLimitRemaining?: number;
+}
+
+// ─── P1: Memory types ───────────────────────────────────────────────
+
+/** A single history entry (append-only log). */
+export interface HistoryEntry {
+  query: string;
+  mode: "search" | "trending";
+  tab?: string;
+  timestamp: number;
+  resultCount: number;
+}
+
+/** A saved bookmark entry. */
+export interface Bookmark {
+  repo: Repo;
+  savedAt: number;
+  tags: string[];
+  notes?: string;
+}
+
+/** A named, saved search. */
+export interface SavedSearch {
+  name: string;
+  query: string;
+  mode: "search" | "trending";
+  tab?: string;
+  sort: SortStrategy;
+  limit: number;
+  createdAt: number;
+  lastRunAt?: number;
+}
+
+/** Session state restored on startup. */
+export interface SessionState {
+  mode: "search" | "trending";
+  query: string;
+  sort: SortStrategy;
+  limit: number;
+  trendingTab: string;
+}
+
+/** Cache entry with TTL. */
+export interface CacheEntry<T> {
+  data: T;
+  cachedAt: number;
+  ttlMs: number;
+}
+
+/** Application config, persisted to ~/.config/ghfind/config.json. */
+export interface Config {
+  githubToken?: string;
+  githubTokens?: string[];
+  defaultSort: SortStrategy;
+  defaultLimit: number;
+  language?: string;
+  theme: string;
+  cacheTtlSeconds: number;
+  defaultTab: "search" | "trending";
+  historySize?: number;
+  bookmarkFile?: string;
+}
+
+/** Abstract search provider. New sources (GitLab, local index, etc.) can
+ *  implement this interface without changing any other layer. */
+export interface SearchProvider {
+  readonly name: string;
+  search(query: ParsedQuery, options: SearchOptions): Promise<SearchResponse>;
 }

package/src/watch.ts

@@ -1,53 +1,62 @@
-/**
- * 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";
-
-export interface WatchOptions {
-  query: string;
-  sort: SearchOptions["sort"];
-  limit: number;
-  token?: string;
-  intervalMs: number;
-  trending?: boolean;
-}
-
-/** Run watch mode. Calls onChange with each tick's results. */
-export async function runWatch(
-  opts: WatchOptions,
-  onChange: (repos: Repo[], delta: number) => void,
-  onError: (err: Error) => void,
-): Promise<void> {
-  let previous: Repo[] = [];
-
-  const tick = async () => {
-    try {
-      const parsed = applyFlagFilters(parseQuery(opts.query), {});
-      const provider = new GitHubSearchProvider(undefined, opts.token ? [opts.token] : []);
-      const options: SearchOptions = {
-        limit: opts.limit,
-        sort: opts.sort,
-        json: false,
-        verbose: false,
-        token: opts.token,
-      };
-      const response = await provider.search(parsed, options);
-      const repos = rankRepos(response.repos, options.sort);
-
-      const delta = previous.length > 0 ? repos.length - previous.length : 0;
-      previous = repos;
-      onChange(repos, delta);
-    } catch (err) {
-      onError(err instanceof Error ? err : new Error(String(err)));
-    }
-  };
-
-  // Immediate first tick, then interval
-  await tick();
-  setInterval(tick, opts.intervalMs);
-}
+/**
+ * Watch mode — periodically re-run a search and show changes.
+ * 
+ */
+import type { ParsedQuery, SearchOptions, Repo } from "./types";
+import { parseQuery, applyFlagFilters, rankRepos, createGitHubSearch } from "./search";
+
+export interface WatchOptions {
+  query: string;
+  sort: SearchOptions["sort"];
+  limit: number;
+  token?: string;
+  intervalMs: number;
+  trending?: boolean;
+}
+
+const MAX_FAILS = 5;
+
+/** Run watch mode. Calls onChange with each tick's results. */
+export async function runWatch(
+  opts: WatchOptions,
+  onChange: (repos: Repo[], delta: number) => void,
+  onError: (err: Error) => void,
+): Promise<void> {
+  let previous: Repo[] = [];
+  let failCount = 0;
+  let intervalId: ReturnType<typeof setInterval> | null = null;
+
+  const tick = async () => {
+    try {
+      const parsed = applyFlagFilters(parseQuery(opts.query), {});
+      const provider = createGitHubSearch(undefined, opts.token ? [opts.token] : []);
+      const options: SearchOptions = {
+        limit: opts.limit,
+        sort: opts.sort,
+        json: false,
+        verbose: false,
+        token: opts.token,
+      };
+      const response = await provider.search(parsed, options);
+      const repos = rankRepos(response.repos, options.sort);
+
+      failCount = 0; // reset on success
+      const delta = previous.length > 0 ? repos.length - previous.length : 0;
+      previous = repos;
+      onChange(repos, delta);
+    } catch (err) {
+      failCount++;
+      onError(err instanceof Error ? err : new Error(String(err)));
+      if (failCount >= MAX_FAILS) {
+        onError(new Error(`Watch stopped after ${MAX_FAILS} consecutive failures`));
+        if (intervalId) clearInterval(intervalId);
+      }
+    }
+  };
+
+  // Immediate first tick, then interval
+  await tick();
+  if (failCount < MAX_FAILS) {
+    intervalId = setInterval(tick, opts.intervalMs);
+  }
+}

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,
-    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);
-}