github-search-cli 0.6.0

package/src/cli.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point — routes between TUI browser and non-interactive modes.
+ *
+ * Usage:
+ *   search-cli                    Launch interactive TUI
+ *   search-cli "query" --json     Search + JSON output
+ *   search-cli "query" --csv      Search + CSV output
+ *   search-cli "query" --markdown Search + Markdown table
+ *   search-cli "query" --count    Just the result count
+ *   search-cli --trending --json  Trending repos as JSON
+ *   search-cli init               Setup wizard
+ *   search-cli --watch "query"    Periodic watch mode
+ *   search-cli --completion bash  Print shell completion
+ *   search-cli --version          Print version
+ *   search-cli --help             Print help
+ */
+import { parseQuery, applyFlagFilters } from "./query.ts";
+import { GitHubSearchProvider } from "./provider.ts";
+import { rankRepos } from "./ranking.ts";
+import { formatRepos, type ExportFormat } from "./export.ts";
+import { formatLines, pipeExec, type FormatLine } from "./pipe.ts";
+import { runWatch } from "./watch.ts";
+import { runInitWizard } from "./init.ts";
+import { readFileSync } from "fs";
+import { launchBrowser } from "./tui.ts";
+import type { SearchOptions } from "./types.ts";
+
+interface CLIFlags {
+  query: string;
+  json: boolean;
+  csv: boolean;
+  markdown: boolean;
+  count: boolean;
+  limit: number;
+  sort: SearchOptions["sort"];
+  token?: string;
+  trending: boolean;
+  since: string;
+  pipe?: string;
+  format?: string;
+  watch: boolean;
+  interval: number;
+  completion?: string;
+  init: boolean;
+  version: boolean;
+  help: boolean;
+}
+
+function parseArgs(args: string[]): CLIFlags {
+  const flags: CLIFlags = {
+    query: "",
+    json: false,
+    csv: false,
+    markdown: false,
+    count: false,
+    limit: 50,
+    sort: "best-match",
+    token: process.env.GITHUB_TOKEN,
+    trending: false,
+    since: "daily",
+    watch: false,
+    interval: 300,
+    init: false,
+    version: false,
+    help: false,
+  };
+
+  let queryParts: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--json": flags.json = true; break;
+      case "--csv": flags.csv = true; break;
+      case "--markdown": flags.markdown = true; break;
+      case "--count": flags.count = true; break;
+      case "--trending": flags.trending = true; break;
+      case "--watch": flags.watch = true; break;
+      case "--version": case "-v": flags.version = true; break;
+      case "--help": case "-h": flags.help = true; break;
+      case "init": flags.init = true; break;
+      case "--limit": flags.limit = parseInt(args[++i]) || 50; break;
+      case "--sort": flags.sort = args[++i] as SearchOptions["sort"]; break;
+      case "--token": flags.token = args[++i]; break;
+      case "--since": flags.since = args[++i]; break;
+      case "--pipe": flags.pipe = args[++i]; break;
+      case "--format": flags.format = args[++i]; break;
+      case "--interval": flags.interval = parseInt(args[++i]) || 300; break;
+      case "--completion": flags.completion = args[++i]; break;
+      default:
+        if (!arg.startsWith("-")) queryParts.push(arg);
+    }
+  }
+  flags.query = queryParts.join(" ");
+  return flags;
+}
+
+async function main() {
+  const flags = parseArgs(process.argv.slice(2));
+
+  // Version
+  if (flags.version) {
+    const pkg = JSON.parse(readFileSync("package.json", "utf-8"));
+    console.log(`search-cli v${pkg.version}`);
+    return;
+  }
+
+  // Help
+  if (flags.help) {
+    console.log(`
+search-cli — Interactive GitHub repository browser
+
+Usage:
+  search-cli                           Launch interactive TUI
+  search-cli <query> --json            Search, output JSON
+  search-cli <query> --csv             Search, output CSV
+  search-cli <query> --markdown        Search, output Markdown table
+  search-cli <query> --count           Just the result count
+  search-cli <query> --format <fmt>    Format lines (urls|names|ssh-urls|clone-commands|ids)
+  search-cli <query> --pipe <target>   Pipe to clone/open
+  search-cli --trending --json         Trending repos as JSON
+  search-cli --watch <query>           Watch mode (poll every Ns)
+  search-cli init                      Run setup wizard
+  search-cli --completion <shell>      Print completion script (bash|zsh|fish)
+  search-cli --version                 Print version
+  search-cli --help                    Print this help
+
+Options:
+  --json, --csv, --markdown, --count   Output format
+  --limit <n>                          Max results (default: 50)
+  --sort <strategy>                    Sort: best-match|stars|updated|forks
+  --token <token>                      GitHub API token
+  --trending                           Trending mode
+  --since <period>                     Trending period: daily|weekly|monthly
+  --pipe <target>                      Pipe target: clone|open
+  --format <fmt>                       Line format: urls|names|ssh-urls|...
+  --watch                              Watch mode (re-run periodically)
+  --interval <s>                       Watch interval in seconds (default: 300)
+  --completion <shell>                 Generate completions
+`);
+    return;
+  }
+
+  // Shell completions
+  if (flags.completion) {
+    const shell = flags.completion;
+    try {
+      const content = readFileSync(`completions/search-cli.${shell}`, "utf-8");
+      console.log(content);
+    } catch {
+      console.error(`Completions not available for shell: ${shell}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Init wizard
+  if (flags.init) {
+    await runInitWizard();
+    return;
+  }
+
+  // Determine output format
+  const format: ExportFormat | undefined =
+    flags.json ? "json" : flags.csv ? "csv" : flags.markdown ? "markdown" : undefined;
+  const isNonInteractive = format || flags.count || flags.format || flags.pipe || flags.watch;
+
+  // Non-interactive mode
+  if (isNonInteractive) {
+    await runNonInteractive(flags, format);
+    return;
+  }
+
+  // Default: launch interactive TUI
+  await launchBrowser();
+}
+
+async function runNonInteractive(flags: CLIFlags, format?: ExportFormat) {
+  const query = flags.query;
+  const provider = new GitHubSearchProvider(undefined, flags.token ? [flags.token] : []);
+
+  // --watch mode
+  if (flags.watch) {
+    let tick = 0;
+    await runWatch(
+      { query, sort: flags.sort, limit: flags.limit, token: flags.token, intervalMs: flags.interval * 1000, trending: flags.trending },
+      (repos, delta) => {
+        tick++;
+        if (format) {
+          console.log(`[Watch #${tick}] ${repos.length} results (${delta >= 0 ? "+" : ""}${delta} since last check)`);
+          console.log(formatRepos(repos, format));
+        } else {
+          console.log(`[Watch #${tick}] ${repos.length} results — ${delta >= 0 ? "+" : ""}${delta} since last check`);
+        }
+      },
+      (err) => console.error(`[Watch error] ${err.message}`),
+    );
+    return;
+  }
+
+  // --pipe mode
+  if (flags.pipe) {
+    const parsed = applyFlagFilters(parseQuery(query), {});
+    const response = await provider.search(parsed, { limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token });
+    const repos = rankRepos(response.repos, flags.sort);
+    await pipeExec(repos, flags.pipe);
+    return;
+  }
+
+  // --format mode
+  if (flags.format) {
+    const parsed = applyFlagFilters(parseQuery(query), {});
+    const response = await provider.search(parsed, { limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token });
+    const repos = rankRepos(response.repos, flags.sort);
+    console.log(formatLines(repos, flags.format as FormatLine));
+    return;
+  }
+
+  // Standard search with format
+  const parsed = applyFlagFilters(parseQuery(query), {});
+  const response = await provider.search(parsed, {
+    limit: flags.limit, sort: flags.sort, json: false, verbose: false, token: flags.token,
+  });
+  const repos = rankRepos(response.repos, flags.sort);
+
+  // --count
+  if (flags.count) {
+    console.log(response.totalCount);
+    return;
+  }
+
+  // --json, --csv, --markdown
+  if (format) {
+    console.log(formatRepos(repos, format));
+    return;
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/compare.ts

@@ -0,0 +1,46 @@
+/**
+ * Repo comparison — side-by-side table for 2+ repos.
+ */
+import type { Repo } from "./types.ts";
+
+interface CompareRow {
+  label: string;
+  values: string[];
+}
+
+/** Build a comparison table as an array of text rows. */
+export function buildComparisonTable(repos: Repo[]): string {
+  if (repos.length < 2) return "Select at least 2 repos to compare (press c to add).";
+
+  const rows: CompareRow[] = [];
+  const names = repos.map((r) => r.fullName);
+
+  rows.push({ label: "Stars", values: repos.map((r) => `★ ${r.stars.toLocaleString()}`) });
+  rows.push({ label: "Forks", values: repos.map((r) => r.forks.toLocaleString()) });
+  rows.push({ label: "Language", values: repos.map((r) => r.language ?? "—") });
+  rows.push({ label: "Created", values: repos.map((r) => r.createdAt?.slice(0, 7) ?? "—") });
+  rows.push({ label: "Updated", values: repos.map((r) => r.updatedAt?.slice(0, 10) ?? "—") });
+  rows.push({ label: "Topics", values: repos.map((r) => (r.topics?.slice(0, 3).join(", ") ?? "—") || "—") });
+
+  // Calculate the max width for each column
+  const colW = Math.max(15, ...names.map((n) => n.length));
+  const valW = Math.max(8, ...rows.flatMap((r) => r.values.map((v) => v.length)));
+
+  // Header row
+  const header = ["".padEnd(14), ...names.map((n) => n.padEnd(colW))];
+  const sep = ["".padEnd(14, "─"), ...names.map(() => "".padEnd(colW, "─"))];
+
+  const lines: string[] = [
+    "┌" + sep.map((s) => "─" + s + "─").join("┬") + "┐",
+    "│" + header.map((h) => ` ${h} `).join("│") + "│",
+    "├" + sep.map((s) => "─" + s + "─").join("┼") + "┤",
+  ];
+
+  for (const row of rows) {
+    const cells = [row.label.padEnd(14), ...row.values.map((v) => v.padEnd(colW))];
+    lines.push("│" + cells.map((c) => ` ${c} `).join("│") + "│");
+  }
+
+  lines.push("└" + sep.map((s) => "─" + s + "─").join("┴") + "┘");
+  return lines.join("\n");
+}

package/src/config.ts

@@ -0,0 +1,66 @@
+/**
+ * Config system: load/save config from XDG paths, merge with env vars.
+ * 
+ * Lookup order:
+ *   1. SEARCH_CLI_CONFIG env var
+ *   2. $XDG_CONFIG_HOME/search-cli/config.json
+ *   3. ~/.config/search-cli/config.json
+ */
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+
+/** Directory for persistent state (history, bookmarks, session). */
+export function stateDir(): string {
+  const xdg = process.env.XDG_STATE_HOME;
+  const base = xdg ? join(xdg, "search-cli") : join(homedir(), ".local", "share", "search-cli");
+  return base;
+}
+
+/** Directory for cache files. */
+export function cacheDir(): string {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg ? join(xdg, "search-cli") : join(homedir(), ".cache", "search-cli");
+  return base;
+}
+import type { Config } from "./types.ts";
+
+const DEFAULTS: Config = {
+  defaultSort: "best-match",
+  defaultLimit: 50,
+  theme: "tokyo-night",
+  cacheTtlSeconds: 300,
+  defaultTab: "search",
+};
+
+export function configPath(): string {
+  const envPath = process.env.SEARCH_CLI_CONFIG;
+  if (envPath) return envPath;
+
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg ? join(xdg, "search-cli") : join(homedir(), ".config", "search-cli");
+  return join(base, "config.json");
+}
+
+export function loadConfig(): Config {
+  const path = configPath();
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    return mergeWithEnv({ ...DEFAULTS, ...parsed });
+  } catch {
+    return mergeWithEnv({ ...DEFAULTS });
+  }
+}
+
+export function saveConfig(config: Config): void {
+  const path = configPath();
+  const dir = path.slice(0, Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")));
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2));
+}
+
+function mergeWithEnv(config: Config): Config {
+  if (process.env.GITHUB_TOKEN) config.githubToken = process.env.GITHUB_TOKEN;
+  return config;
+}

package/src/deepdive.ts

@@ -0,0 +1,124 @@
+/**
+ * Repo deep-dive — fetch and format rich repo details.
+ * 
+ * ponytail: single fetch-all function, no section tab navigation.
+ * Shows: summary, languages bar, top contributors, README excerpt.
+ * Skip: releases (YAGNI), dependency graph (auth-gated).
+ */
+import type { Repo } from "./types.ts";
+import { NetworkError } from "./errors.ts";
+
+const USER_AGENT = "search-cli/1.0";
+
+/** Language breakdown: { [lang]: bytes } */
+type LanguageMap = Record<string, number>;
+
+/** Contributor summary */
+interface Contributor {
+  login: string;
+  contributions: number;
+}
+
+/** All deep-dive data for one repo. */
+export interface DeepDiveData {
+  summary: string;
+  languages: string;
+  contributors: string;
+  readme: string;
+}
+
+/** Fetch all deep-dive data for a repo. Returns formatted sections. */
+export async function fetchDeepDive(repo: Repo, token?: string): Promise<DeepDiveData> {
+  const auth = token ? { Authorization: `Bearer ${token}` } : {};
+  const headers = { "User-Agent": USER_AGENT, ...auth };
+
+  const [languagesRes, contributorsRes] = await Promise.all([
+    fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}/languages`, { headers }),
+    fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}/contributors?per_page=5`, { headers }),
+  ]);
+
+  // README with branch fallback: main → master → README.rst
+  let readmeText = "";
+  for (const path of [`${repo.owner}/${repo.name}/main/README.md`, `${repo.owner}/${repo.name}/master/README.md`, `${repo.owner}/${repo.name}/main/README.rst`]) {
+    const r = await fetch(`https://raw.githubusercontent.com/${path}`, { headers });
+    if (r.ok) { readmeText = await r.text(); break; }
+  }
+
+  return {
+    summary: formatSummary(repo),
+    languages: formatLanguages(languagesRes.ok ? await languagesRes.json().catch(() => ({})) : {}),
+    contributors: formatContributors(contributorsRes.ok ? await contributorsRes.json().catch(() => []) : []),
+    readme: formatReadme(readmeText),
+  };
+}
+
+function formatSummary(repo: Repo): string {
+  const lines = [
+    ` ${repo.fullName}`,
+    ` ★ ${repo.stars.toLocaleString()}  ◆ ${repo.forks.toLocaleString()}  ${repo.language ?? "—"}`,
+    repo.description ? ` ${repo.description}` : "",
+    repo.topics.length ? ` topics: ${repo.topics.slice(0, 8).join(", ")}` : "",
+    ` ${repo.url}`,
+  ];
+  return lines.filter(Boolean).join("\n");
+}
+
+function formatLanguages(langs: LanguageMap): string {
+  const entries = Object.entries(langs);
+  if (entries.length === 0) return "  (no language data)";
+  const total = entries.reduce((s, [, v]) => s + v, 0);
+  const barW = 20;
+  return entries
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 8)
+    .map(([name, bytes]) => {
+      const pct = ((bytes / total) * 100).toFixed(1);
+      const filled = Math.round((bytes / total) * barW);
+      const bar = "█".repeat(filled) + "░".repeat(barW - filled);
+      return `  ${name.padEnd(16)} ${bar} ${pct}%`;
+    })
+    .join("\n");
+}
+
+function formatContributors(contributors: Contributor[]): string {
+  if (contributors.length === 0) return "  (no contributor data)";
+  return contributors
+    .slice(0, 5)
+    .map((c) => `  ▲ ${c.login.padEnd(20)} ${c.contributions} commits`)
+    .join("\n");
+}
+
+function formatReadme(readme: string): string {
+  if (!readme) return "  (no README)";
+  // Strip markdown formatting for terminal display
+  const stripped = readme
+    .replace(/```[\s\S]*?```/g, "[code block]")
+    .replace(/#{1,6}\s/g, "")
+    .replace(/\*\*(.+?)\*\*/g, "$1")
+    .replace(/\[(.+?)\]\(.+?\)/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  
+  const lines = stripped.slice(0, 30);
+  if (stripped.length > 30) lines.push("... (more lines, open in browser to read full)");
+  return lines.map((l) => `  ${l}`).join("\n");
+}
+
+/** Build the full deep-dive display text from data. */
+export function buildDeepDiveText(data: DeepDiveData): string {
+  return [
+    "── Summary ──────────────────────────────────────",
+    data.summary,
+    "",
+    "── Languages ────────────────────────────────────",
+    data.languages,
+    "",
+    "── Top Contributors ─────────────────────────────",
+    data.contributors,
+    "",
+    "── README ───────────────────────────────────────",
+    data.readme,
+  ].join("\n");
+}

package/src/errors.ts

@@ -0,0 +1,62 @@
+/**
+ * Structured error types with user-facing messages.
+ * Every error knows what to tell the user and (optionally) what to do next.
+ */
+
+export class SearchCliError extends Error {
+  constructor(
+    message: string,
+    public readonly userMessage: string,
+    public readonly recoverable: boolean = true,
+  ) {
+    super(message);
+    this.name = "SearchCliError";
+  }
+}
+
+export class NetworkError extends SearchCliError {
+  constructor() {
+    super(
+      "Network request failed",
+      "⚠ Network error — check your connection. Retrying in 5s... [r]etry now",
+    );
+    this.name = "NetworkError";
+  }
+}
+
+export class RateLimitError extends SearchCliError {
+  constructor(public readonly hasToken: boolean, resetSeconds?: number) {
+    const msg = hasToken
+      ? `⚠ API rate limit exceeded. Resets in ${resetSeconds ?? "?"}s. [r]etry [c]hange token`
+      : "⚠ Rate limited (10/min). Set GITHUB_TOKEN for 30/min, or wait. [r]etry";
+    super(msg, msg);
+    this.name = "RateLimitError";
+  }
+}
+
+export class BadQueryError extends SearchCliError {
+  constructor(public readonly detail: string) {
+    super(`Invalid query: ${detail}`, `⚠ Invalid query: ${detail}`);
+    this.name = "BadQueryError";
+  }
+}
+
+export class NoResultsError extends SearchCliError {
+  constructor(public readonly query: string) {
+    super(
+      `No results for "${query}"`,
+      `🔍 No results for "${query}". Tips: check spelling, try fewer qualifiers, or [b]rowse trending`,
+    );
+    this.name = "NoResultsError";
+  }
+}
+
+export class ParseError extends SearchCliError {
+  constructor(source: string, detail: string) {
+    super(
+      `Parse error from ${source}: ${detail}`,
+      `⚠ Could not parse ${source}. GitHub may have changed the layout. [r]etry`,
+    );
+    this.name = "ParseError";
+  }
+}

package/src/explore.ts

@@ -0,0 +1,45 @@
+/**
+ * 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);
+}

package/src/export.ts

@@ -0,0 +1,56 @@
+/**
+ * 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;
+}

package/src/help.ts

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