Merge pull request #83 from fulll/feat/tui-cosmetics

feat: TUI cosmetics v1.8.0 — purple theme, progress bar, position indicator, line-anchored links

Author: shouze

CHANGELOG.md

@@ -6,6 +6,7 @@ Each release entry covers the motivation, new features, breaking changes (if any
 
 | Version                                                                  | Blog post                                                                                                       |
 | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| [v1.8.0](https://fulll.github.io/github-code-search/blog/release-v1-8-0) | Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, Esc to close help           |
 | [v1.7.0](https://fulll.github.io/github-code-search/blog/release-v1-7-0) | Shell completions (bash/zsh/fish) + extended syntax highlighting (PHP, C/C++, Swift, Terraform/HCL, Dockerfile) |
 | [v1.6.1](https://fulll.github.io/github-code-search/blog/release-v1-6-1) | Fix TUI only displaying first text fragment when a file has multiple matches                                    |
 | [v1.6.0](https://fulll.github.io/github-code-search/blog/release-v1-6-0) | Power navigation: global fold/unfold, gg/G top/bottom, paged scroll, open-in-browser                            |

demo/demo.gif

@@ -11,6 +11,7 @@ Full release notes and changelogs are always available on
 
 | Release                    | Highlights                                                                                                 |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| [v1.8.0](./release-v1-8-0) | Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, Esc to close help      |
 | [v1.7.0](./release-v1-7-0) | Shell completions (bash/zsh/fish), extended syntax highlighting (PHP, C/C++, Swift, Terraform, Dockerfile) |
 | [v1.6.1](./release-v1-6-1) | Fix TUI rendering only the first fragment for multi-match files                                            |
 | [v1.6.0](./release-v1-6-0) | Power navigation: global fold/unfold (`Z`), Vim `gg`/`G` jumps, paged scroll, open-in-browser (`o`)        |

docs/blog/index.md

@@ -0,0 +1,70 @@
+---
+title: "What's new in v1.8.0"
+description: "Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, and Esc to close help."
+date: 2026-03-04
+---
+
+# What's new in github-code-search v1.8.0
+
+> Full release notes: <https://github.com/fulll/github-code-search/releases/tag/v1.8.0>
+
+## Highlights
+
+### Cohesive purple TUI theme
+
+The interactive view has been completely re-skinned around a purple colour palette.
+
+| Element                 | Before            | After                           |
+| ----------------------- | ----------------- | ------------------------------- |
+| Active row background   | Grey (`48;5;236`) | Dark purple (`48;5;53`)         |
+| Active row left bar `▌` | None              | Saturated purple (`38;5;129`)   |
+| Repo names              | Bold cyan         | Bright purple bold (`38;5;129`) |
+| Match count badge       | Dim white         | Muted purple (`38;5;99`)        |
+
+The left bar spans the full terminal width so the selected row is unmistakable even in long result lists.
+Path and loc-suffix (`:line:col`) on the active extract row use **bold white** for visual consistency.
+
+### Fetch progress bar
+
+A progress bar is now displayed during the GitHub API search so you can track paged requests in real time:
+
+```
+Fetching results ████████████████░░░░░░░░  8/13 pages
+```
+
+The bar fills in saturated purple and shows the current page / estimated total pages.
+It disappears automatically when all results are loaded.
+
+### Position indicator
+
+A persistent indicator at the bottom of the TUI shows your exact position within the result list:
+
+```
+  ↕ row 14 of 49
+```
+
+The number always reflects the **cursor position**, not the scroll offset, so it updates on every keypress — including when you navigate upward inside an already-scrolled viewport.
+
+### Line-anchored file links (`o`)
+
+When you press `o` on an **extract row**, the browser now opens the file at the **exact matched line** by appending a `#L{line}` anchor to the GitHub URL.
+
+Before: `https://github.com/org/repo/blob/main/src/foo.ts`  
+After: `https://github.com/org/repo/blob/main/src/foo.ts#L42`
+
+On a **repo row**, `o` still opens the repository home page unchanged.
+
+### Esc to close the help overlay
+
+The help overlay (toggled with `h` or `?`) can now also be dismissed with `Esc`, matching the expected behaviour of most terminal UIs.
+
+---
+
+## Upgrade
+
+```bash
+github-code-search upgrade
+```
+
+Or grab the latest binary directly from the
+[GitHub Releases page](https://github.com/fulll/github-code-search/releases/tag/v1.8.0).

docs/blog/release-v1-8-0.md

@@ -1,5 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { fetchAllResults, fetchRepoTeams, searchCode, segmentLineCol } from "./api.ts";
+import {
+  buildFetchProgress,
+  fetchAllResults,
+  fetchRepoTeams,
+  searchCode,
+  segmentLineCol,
+} from "./api.ts";
 
 const originalFetch = globalThis.fetch;
 const originalSetTimeout = globalThis.setTimeout;
@@ -506,3 +512,35 @@ describe("fetchRepoTeams", () => {
     expect(result.has("myorg/repo-a")).toBe(true);
   });
 });
+
+// ─── buildFetchProgress ───────────────────────────────────────────────────────
+
+describe("buildFetchProgress", () => {
+  it("starts with \\r to overwrite the current line", () => {
+    const s = buildFetchProgress(1, 10);
+    expect(s.startsWith("\r")).toBe(true);
+  });
+
+  it("contains bright purple ANSI escape 38;5;129m", () => {
+    const s = buildFetchProgress(1, 10);
+    expect(s).toContain("\x1b[38;5;129m");
+  });
+
+  it("contains page counter text", () => {
+    const s = buildFetchProgress(3, 10);
+    const stripped = s.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(stripped).toContain("3/10");
+  });
+
+  it("full bar when currentPage equals totalPages — no empty block character", () => {
+    const s = buildFetchProgress(10, 10);
+    const stripped = s.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(stripped).not.toContain("░");
+  });
+
+  it("empty bar at page 0 — no filled block character", () => {
+    const s = buildFetchProgress(0, 10);
+    const stripped = s.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(stripped).not.toContain("▓");
+  });
+});

src/api.test.ts

@@ -144,23 +144,54 @@ export async function searchCode(
   return { items: data.items ?? [], total: data.total_count ?? 0 };
 }
 
+// ─── Fetch progress bar ───────────────────────────────────────────────────────
+
+const PROGRESS_BAR_WIDTH = 20;
+
+/**
+ * Build a single-line purple progress bar string suitable for writing to
+ * stderr with a leading \r so it overwrites the current line.
+ *
+ * Pure function — no side effects; exported for unit testing.
+ */
+export function buildFetchProgress(currentPage: number, totalPages: number): string {
+  const filled = totalPages > 0 ? Math.round((currentPage / totalPages) * PROGRESS_BAR_WIDTH) : 0;
+  const empty = PROGRESS_BAR_WIDTH - filled;
+  // \x1b[38;5;129m — bright purple (filled blocks)
+  // \x1b[38;5;240m — dark grey (empty blocks)
+  const bar = `\x1b[38;5;129m${"▓".repeat(filled)}\x1b[38;5;240m${"░".repeat(empty)}\x1b[0m`;
+  return `\r  Fetching results from GitHub… ${bar}  page ${currentPage}/${totalPages}`;
+}
+
 export async function fetchAllResults(
   query: string,
   org: string,
   token: string,
 ): Promise<CodeMatch[]> {
-  process.stderr.write(pc.dim("Fetching results from GitHub…\n"));
+  // Write the initial progress line (no newline — will be overwritten by \r).
+  process.stderr.write(pc.dim("  Fetching results from GitHub…"));
+  let totalPages = 0;
   // GitHub code search is capped at 1000 results; paginatedFetch stops naturally
   // when a page returns fewer than 100 items (or the API returns an empty page
   // after the cap is reached).
   const allItems = await paginatedFetch<RawCodeItem>(
     async (page) => {
-      const { items } = await searchCode(query, org, token, page);
+      const { items, total } = await searchCode(query, org, token, page);
+      // On the first page, compute the expected number of pages so the bar
+      // can show realistic progress. GitHub caps at 1 000 results (10 pages).
+      if (page === 1) {
+        totalPages = Math.min(Math.ceil(total / 100), 10);
+      }
+      if (totalPages > 0) {
+        process.stderr.write(buildFetchProgress(page, totalPages));
+      }
       return items;
     },
     100, // GitHub returns up to 100 items per page
     250, // Be kind to rate limits between pages
   );
+  // Terminate the progress line.
+  process.stderr.write("\n");
 
   // ─── Resolve absolute line numbers ──────────────────────────────────────
   // The GitHub Code Search API returns fragment-relative character indices