github-search-cli 9.8.3 → 9.10.0

package/docs/HOW-TO.md

@@ -0,0 +1,255 @@
+# How to use ghfind
+
+A task-oriented guide. For the flag and keybinding _reference_, see
+[`README.md`](../README.md) and `ghfind --help`; this page is about **getting a
+good result out of a query**, and what to do when one goes wrong.
+
+- [Set up a token first](#set-up-a-token-first)
+- [Write a query](#write-a-query)
+- [Qualifier reference](#qualifier-reference)
+- [Read the results](#read-the-results)
+- [When a search returns nothing](#when-a-search-returns-nothing)
+- [When something goes wrong](#when-something-goes-wrong)
+- [Recipes](#recipes)
+- [Environment variables](#environment-variables)
+
+---
+
+## Set up a token first
+
+Without a token GitHub allows **60 requests/hour** from your IP. With one you
+get **5,000/hour**. A TUI session that pages through results will exhaust 60
+fast, so a token is the difference between a usable session and a session that
+stops halfway through.
+
+```bash
+ghfind login          # interactive: paste a token, saved to config
+```
+
+Or set it for one shell session:
+
+```bash
+export GITHUB_TOKEN=ghp_yourtoken
+```
+
+Create a token at **GitHub → Settings → Developer settings → Personal access
+tokens**. For searching public repositories no scopes are required; a
+fine-grained token with no extra permissions is fine. Confirm it took effect:
+
+```bash
+ghfind --doctor
+```
+
+A token is optional — everything below works without one, just with a much
+smaller budget.
+
+---
+
+## Write a query
+
+A query is free text plus optional `qualifier:value` filters:
+
+```bash
+ghfind "terminal http client language:Rust"
+```
+
+Three things to know:
+
+**1. Typos in qualifiers are corrected, not rejected.** `langauge:Rust`,
+`star:1000` and `push:>2024-01-01` all work — ghfix maps them to `language:`,
+`stars:` and `pushed:`. Only qualifiers ghfind knows are corrected, so a
+qualifier it has never heard of (`is:`, `has:`, `props.*`) is passed through
+untouched rather than mangled into something else.
+
+**2. Counts accept `k` and `m`.** `stars:10k` means 10,000 or more. Without a
+suffix, a bare number means _exactly_ that number — `stars:100` matches repos
+with exactly 100 stars, which is rarely what you want, so prefer `stars:>=100`
+or `stars:10k`.
+
+```bash
+ghfind "cli stars:10k"          # 10,000 or more
+ghfind "cli stars:>=10000"      # identical
+ghfind "cli stars:1k..10k"      # between 1,000 and 10,000
+```
+
+**3. Quote multi-word phrases.** Unquoted, every word is a separate term:
+
+```bash
+ghfind '"machine learning" language:Python'   # the phrase
+ghfind 'machine learning language:Python'     # both words, anywhere
+```
+
+Prefix any qualifier with `-` to exclude it:
+
+```bash
+ghfind "cli topic:cli -language:JavaScript"
+```
+
+---
+
+## Qualifier reference
+
+| Qualifier     | Example                    | Notes                                     |
+| ------------- | -------------------------- | ----------------------------------------- |
+| `language:`   | `language:Rust`            |                                           |
+| `stars:`      | `stars:10k`, `stars:>=500` | count, `k`/`m` sugar, `a..b` range        |
+| `forks:`      | `forks:>100`               | count                                     |
+| `topics:`     | `topics:>3`                | number of topics a repo has               |
+| `followers:`  | `followers:>=10000`        | count                                     |
+| `size:`       | `size:<1000`               | kilobytes                                 |
+| `fork:`       | `fork:true`, `fork:only`   | `fork` is a boolean, `forks` is a count   |
+| `archived:`   | `archived:false`           | boolean                                   |
+| `topic:`      | `topic:machine-learning`   | one topic (repeat for more)               |
+| `user:`       | `user:torvalds`            | repos owned by a user                     |
+| `org:`        | `org:rust-lang`            | repos owned by an organization            |
+| `repo:`       | `repo:facebook/react`      | one exact repository                      |
+| `in:`         | `in:name,description`      | `name`, `description`, `topics`, `readme` |
+| `pushed:`     | `pushed:>2024-01-01`       | `YYYY-MM-DD`                              |
+| `created:`    | `created:>2020-01-01`      | `YYYY-MM-DD`                              |
+| `updated:`    | `updated:>2024-06-01`      | `YYYY-MM-DD`                              |
+| `license:`    | `license:apache-2.0`       | SPDX-ish keyword                          |
+| `visibility:` | `visibility:public`        | `public`, `private`, `internal`           |
+
+An invalid value is rejected **before** the request is sent, with the fix in the
+message:
+
+```console
+$ ghfind "cli stars:abc"
+⚠ Invalid query: "stars:abc" is not a number — use stars:100, stars:>=100, or stars:1k..10k
+  Try: cli
+```
+
+---
+
+## Read the results
+
+Results are shown in the TUI. In the CLI, `--json` / `--csv` / `--markdown`
+give you the same data in a form you can pipe:
+
+```bash
+ghfind "cli language:Rust" --json | jq -r '.[].fullName'
+ghfind "cli language:Rust" --json | jq 'length'      # how many came back
+ghfind "cli language:Rust" --markdown                # for pasting into an issue
+```
+
+Sort changes the order, not the query:
+
+```bash
+ghfind "cli" --sort stars      # most-starred
+ghfind "cli" --sort updated    # most recently touched
+ghfind "cli" --sort forks
+ghfind "cli" --sort best-match # GitHub's own relevance order
+```
+
+In the TUI, `Esc` opens the leader menu (or click the <kbd>☰ menu</kbd> button in
+the bottom-right corner), where **Sort** cycles the same strategies without
+leaving the results.
+
+---
+
+## When a search returns nothing
+
+ghfind ranks the qualifiers by how likely each is to be what killed the
+result, and suggests a loosened query rather than a generic "try again":
+
+```console
+🔍 No results for "rust stars:>=5000000".
+  Try: rust stars:>=500000
+```
+
+Each suggestion rewrites one qualifier instead of dropping it, so the retry is
+still a recognisable version of your question. The order reflects how sharply
+each filter narrows things: a star or size threshold empties a result set
+outright, so those are loosened first and a `language:` filter — which matches
+plenty on its own — is touched last.
+
+If a suggestion still returns nothing, the qualifier you most care about is
+probably `repo:`, `user:` or `org:` — those restrict to a single account.
+
+---
+
+## When something goes wrong
+
+| Message                              | Meaning                                      | Fix                                                                                            |
+| ------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `API rate limit exceeded (60/hr)`    | No token, or the hourly budget is spent      | `ghfind login`, or wait for the reset                                                          |
+| `API rate limit exceeded (5,000/hr)` | Authenticated budget spent                   | Wait, or `c` in the TUI to swap tokens                                                         |
+| `Bad GitHub token (401)`             | Token rejected — usually revoked or mistyped | `t` in the TUI, or `ghfind login`                                                              |
+| `Forbidden (403)`                    | Authenticated but not allowed                | Read the reason in the message; often SSO not authorizing the token, or a secondary rate limit |
+| `Network error`                      | Genuine connectivity or a 5xx                | Retry with `r`                                                                                 |
+
+While one of these is showing in the TUI status bar, these keys work:
+
+| Key | Action                                                |
+| --- | ----------------------------------------------------- |
+| `r` | Retry                                                 |
+| `t` | Fix the token inline (saves it and re-runs the query) |
+| `u` | Drop the token and retry unauthenticated              |
+| `c` | Swap in a different token (rate limit)                |
+
+**To see the actual reason behind an error**, set `GHFIND_LOG` — the TUI owns
+the screen and cannot print diagnostics into it, so it writes them to a file:
+
+```bash
+GHFIND_LOG=/tmp/ghfind.log ghfind
+# then quit with q and read the log
+```
+
+A `403` includes the response body, which names the real cause; token values
+are redacted from logged URLs.
+
+---
+
+## Recipes
+
+```bash
+# Popular, actively maintained Rust CLI tools
+ghfind "cli language:Rust stars:10k -archived:true"
+
+# Something big and recently touched by a specific org
+ghfind "org:rust-lang pushed:>2025-01-01"
+
+# Exactly this repository
+ghfind "repo:facebook/react"
+
+# Topic + size ceiling (small, focused libraries)
+ghfind "topic:parser size:<500 stars:>=100"
+
+# Find the name of a project you half-remember
+ghfind "json schema validator in:name"
+
+# Just how many repos match (no output formatting)
+ghfind "topic:cli language:Rust" --count
+
+# Top 5 by stars, as CSV
+ghfind "topic:cli" --sort stars --limit 5 --csv
+
+# Watch a query for new results
+ghfind "topic:ai language:Rust" --watch --interval 300
+
+# Trending instead of searching
+ghfind --trending --since weekly
+ghfind --trending rust --count
+
+# Pipe into another tool
+ghfind "cli language:Rust" --json | jq -r '.[].url'
+```
+
+---
+
+## Environment variables
+
+| Variable          | Effect                                                  |
+| ----------------- | ------------------------------------------------------- |
+| `GITHUB_TOKEN`    | Raises the rate limit from 60/hr to 5,000/hr            |
+| `GHFIND_CONFIG`   | Config file path, overriding the XDG lookup             |
+| `GHFIND_LOG`      | Write TUI diagnostics to this file                      |
+| `NO_COLOR`        | Disables colored `--doctor` output                      |
+| `XDG_CONFIG_HOME` | Relocates `~/.config` (config lives at `<dir>/ghfind/`) |
+| `XDG_STATE_HOME`  | Relocates history/bookmarks/session state               |
+
+`GITHUB_TOKEN` takes precedence over a token saved in the config file.
+
+See [`README.md`](../README.md) for the full flag, subcommand and keybinding
+reference, [`CONTRIBUTING.md`](../CONTRIBUTING.md) for development commands, and
+[`CHANGELOG.md`](../CHANGELOG.md) for what changed in each release.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-search-cli",
-  "version": "9.8.3",
-  "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
+  "version": "9.10.0",
+  "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard + mouse TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",
   "volta": {
@@ -21,6 +21,7 @@
     "src/",
     "scripts/",
     "completions/",
+    "docs/",
     "demo.svg",
     "LICENSE",
     "CHANGELOG.md",

package/release-notes/9.10.0.md

@@ -0,0 +1,137 @@
+# v9.10.0
+
+ghfind's TUI has always been keyboard-only — and, quietly, half-broken for the
+mouse. OpenTUI was already emitting SGR mouse tracking and hit-testing every
+event into a target renderable. Nothing in ghfind consumed any of it. The
+events were parsed, dispatched, and thrown away. This release makes the TUI
+clickable, and fixes the two keyboard rough edges that were hiding behind it.
+
+## The TUI is now fully clickable
+
+Click a result and the detail pane updates. Click it again and your browser
+opens. Scroll to move through results. Click outside an overlay to close it.
+
+Every list, card, tab and button responds: the results list, the landing mode
+cards, trending tabs, the update dialog's buttons, and every overlay list
+(history, bookmarks, saved searches, topics, export, share, and the command
+menu itself).
+
+The important detail is that clicks do not reimplement anything. A click calls
+`setSelectedIndex`, which emits the same `selectionChanged` event `↑`/`↓`
+already emitted, so the detail pane, the detail graph and the packages view all
+work identically without a parallel code path. A double-click calls the same
+activation path as `Enter`. There is no mouse branch to keep in sync — the
+keyboard and the mouse converge on one implementation, which is also why they
+cannot drift.
+
+## The wheel scrolled the wrong pane
+
+Worth calling out, because it predates this release and was a real bug rather
+than a missing feature.
+
+When a scroll event hit nothing, OpenTUI falls back to delivering it to
+whatever renderable currently holds focus. In ghfind that was almost always the
+results list. So opening the README viewer and scrolling would move the
+_result selection_ instead of the README — the one thing you were trying to do.
+
+Every scrollable region now claims the wheel explicitly, and the list's wheel
+handler steps the selection through `moveUp`/`moveDown`, so wheel navigation
+and `↑`/`↓` navigation cannot diverge either.
+
+## Text that swallowed clicks
+
+`TextRenderable` defaults to OpenTUI's `selectable: true`, and a left-press on
+a selectable renderable is consumed as a text-selection drag _before_ the app's
+own handlers run. The detail pane, comparison table, tab bar and other read-only
+text are all `TextRenderable`s, so clicks landing on them did nothing at all.
+
+They now opt out of text selection. The query input deliberately keeps it, so
+clicking into the input still places your cursor.
+
+## A hover highlight that painted the list magenta
+
+Small one, but it would have been immediately obvious to anyone using it.
+OpenTUI's colour parser accepts `"transparent"`, CSS colour names, and 3/4/6/8
+digit hex — nothing else. An `rgba(255,255,255,0.06)` hover tint failed that
+check and fell through to its magenta fallback, so hovering a list would have
+flashed it magenta. Now written as `#ffffff0f`.
+
+Found because the test harness prints that warning. Worth noting the class of
+bug: OpenTUI degrades an invalid colour to magenta rather than throwing, so this
+fails silently and visibly at the same time.
+
+## `Space` opened the menu only if you had clicked something first
+
+The subtlest problem in this release, and it was not caused by mouse support —
+it was exposed by it.
+
+The query input is focused by default. The command menu was bound to `Space`,
+gated on the input _not_ being focused, so that spaces could still be typed into
+a query. That gate meant `Space` opened the menu only when focus had moved
+somewhere else. The one way focus moved was clicking a result row: OpenTUI's
+auto-focus-on-press walks up from the pressed renderable to the nearest
+focusable ancestor, finds the results list, and focuses it — blurring the input
+as a side effect.
+
+So on a fresh launch, `Space` typed a space. Click any row, and `Space` opened
+the menu. Same key, same screen, different behaviour depending on invisible
+state.
+
+A regression test now pins this down from both directions: with `keepFocus` a row
+click does not move focus, and without it one does.
+
+The resolution is that **`Esc` opens the command menu**, and `Space` always
+types. `Esc` already closed every overlay, so this adds a meaning rather than
+replacing one. For anyone who prefers not to reach for `Esc`, there is now a
+<kbd>☰ menu</kbd> button in the bottom-right corner — clickable, it floats above
+the layout, and it hides while an overlay is open so it never sits on top of one.
+
+## Added
+
+- Full mouse support: click to select, double-click to open, wheel to scroll,
+  click-outside to dismiss, hover feedback with a pointer cursor.
+- <kbd>☰ menu</kbd> button in the bottom-right corner to open the command menu.
+- A "Mouse" section in the in-app help, documenting every binding.
+- README keybinding tables gained a mouse table; the command-menu references
+  across the README and `docs/HOW-TO.md` now say `Esc` instead of `Space`.
+
+## Fixed
+
+- The scroll wheel scrolled the focused renderable rather than the pane under
+  the pointer, so long-pane scrolling moved the result selection instead.
+- Non-interactive text consumed left-presses as text-selection drags, so clicks
+  over the detail pane and comparison table did nothing.
+- The hover tint used an `rgba()` string that OpenTUI's colour parser rejects,
+  rendering the list magenta.
+- `Space` could not open the command menu on a fresh launch, because it was
+  gated on focus that only moved after a mouse click.
+
+## Verification
+
+The suite grew by 33 tests, to 657.
+
+- **15 unit tests** on the click→row geometry: scroll offsets, multi-line rows
+  (overlay lists render a description line, so each option is two lines tall),
+  `itemSpacing`, clicks past the last row, unmeasured renderables, and empty
+  lists. OpenTUI keeps `scrollOffset` and `linesPerItem` private, so this
+  arithmetic is read through a single narrow cast — the tests are what keep that
+  cast honest.
+- **12 integration tests** driving the real handlers with OpenTUI's mock mouse
+  against a live renderer: click-selects, double-click-opens, the double-click
+  window expiring, click-outside dismissal, row clicks _not_ leaking to the
+  enclosing panel, focus behaviour with and without `keepFocus`, and wheel
+  stepping including both ends of the list.
+- **4 button tests** asserting the corner button actually lands in the
+  bottom-right, that hidden buttons neither render nor take clicks, and that its
+  click does not bubble.
+
+The first two geometry tests failed on the run that wrote them, and caught a
+real off-by-one: the empty area below a short list returned "no row" instead of
+resolving to the last row, which would have dismissed an overlay instead of
+selecting its final entry. That is the exact class of bug that would have been
+very annoying and very hard to report.
+
+`test`, `format:check`, `lint` (Biome) and `typecheck` (tsc) are all green, and
+`bun run build` succeeds. The TUI was also driven end-to-end in a pty to confirm
+the menu opens from both `Esc` and the corner button, since the mock mouse does
+not exercise a real terminal's mouse reporting.

package/release-notes/9.9.0.md

@@ -0,0 +1,193 @@
+# v9.9.0
+
+ghfind used to hand your query straight to GitHub: whatever you typed was
+string-concatenated into an API URL. A misspelled qualifier or a malformed
+value became an opaque `422` from GitHub, or — worse — a **"network error"**
+naming a connectivity problem you did not have. This release makes ghfind
+_understand_ the query before spending a request on it, and adds a
+task-oriented guide for using it.
+
+## A typo in a qualifier no longer ruins the search
+
+`matchQualifier` accepted any word before a colon as a qualifier key, so
+`langauge:Rust` was not treated as the typo it was — it was forwarded verbatim
+and GitHub rejected it with an error that named nothing useful. Now:
+
+```console
+$ ghfind "cli langauge:Rust stars:10k"
+# runs as: cli language:Rust stars:>=10000
+```
+
+Misspellings are corrected two ways: a table of common ones (`langauge`,
+`star`, `licence`, `push`), plus a bounded edit-distance pass that catches the
+rest (`starss` → `stars`).
+
+**The correction is deliberately narrow.** It only touches the qualifiers
+ghfind knows. `is:public`, `has:funding-file` and `props.environment:prod` are
+valid GitHub syntax that ghfind has no business rewriting — and two real bugs
+came from trying:
+
+- `is` sits one edit from the known qualifier `in`, so an unguarded fuzzy pass
+  turned `is:public` into `in:public`, which validation then rejected. Fuzzy
+  correction is now skipped for keys under four characters.
+- Ambiguous input (`sizet`) is left alone rather than rewritten arbitrarily —
+  with two candidates equally close there is not enough signal to guess.
+
+`props.*` had the opposite problem: custom-property keys contain a dot, which
+the parser's key charset rejected, so `props.environment:production` silently
+degraded into a literal keyword. The charset now allows one dot.
+
+## A bad value fails before the request, naming the fix
+
+Every qualifier now has a value rule — numeric counts for `stars`/`forks`/
+`size`/`topics`/`followers`, booleans for `archived`, `true|false|only` for
+`fork`, ISO8601 dates for `created`/`pushed`/`updated`, the `visibility:`
+enum, and the `in:` searchable fields:
+
+```console
+$ ghfind "cli stars:abc"
+⚠ Invalid query: "stars:abc" is not a number — use stars:100, stars:>=100, or stars:1k..10k
+  Try: cli
+```
+
+Dates are checked against the calendar, not just the shape — `2024-02-31` and
+`2023-02-29` are rejected, which `Date.parse` would have quietly rolled over.
+Documented comma-lists like `in:name,description` and the `fork:only` form are
+accepted, because rejecting a valid form is worse than passing a bad one
+through.
+
+## One gate, enforced everywhere
+
+`validateQuery` existed but was called by **the TUI only**. The CLI, the MCP
+server and `--watch` all skipped it, so the single rule it enforced
+(`visibility:` + `private:`) applied in one of four places. All four now go
+through it, and for agents a malformed query returns a readable message with
+`invalidQuery: true` rather than a tool failure that reads as breakage.
+
+`--watch` validates before its poll loop starts: a malformed query is not
+transient, so retrying it five times just printed the same error five times.
+
+## Counts: `10k` works, and `100` still means exactly 100
+
+`stars:10k` → `stars:>=10000`, `size:1m` → `size:>=1000000`,
+`stars:1k..10k` → `stars:1000..10000`.
+
+A bare number is left alone, and that is the subtle part: GitHub reads
+`stars:100` as _exactly_ 100 stars. Rewriting it to `>=100` — which a first
+pass here did — silently changes the question being asked. Verified live:
+
+    stars:100 language:Rust      -> 118 repos
+    stars:>=10000 language:Rust  -> 256 repos
+
+## Zero results now come with a way out
+
+Previously: _"check spelling, try fewer qualifiers, or browse trending."_
+Now ghfind ranks the qualifiers by how sharply each one narrows the corpus and
+offers a concrete retry:
+
+```console
+🔍 No results for "rust stars:>=5000000".
+  Try: rust stars:>=500000
+```
+
+A star or size threshold empties a result set outright, so those are loosened
+first; a plain `language:` filter matches plenty on its own, so it is touched
+last. Each suggestion rewrites one qualifier rather than dropping it, keeping
+the retry a recognisable version of the original question. A negated filter is
+never suggested for removal — it can only widen a search, so it cannot be what
+emptied it.
+
+## A 403 no longer claims SSO is the cause
+
+Found while testing this: the TUI showed `Forbidden (403). If your org
+enforces SSO…` and nothing else. Three unrelated conditions produce a 403 with
+rate-limit budget remaining — SSO not authorizing the token, a secondary/abuse
+rate limit, and org resource restrictions — and the message asserted the first
+one unconditionally. For someone who was actually being secondary-rate-limited,
+that sent them to fix a credential problem that did not exist.
+
+The message now reports GitHub's own explanation and names both plausible
+causes. To see which one it is, `GHFIND_LOG=<path>` writes diagnostics to a
+file — the TUI owns the screen and cannot print them into it, and its logger
+used to be a silent no-op, which is why this was undiagnosable in the first
+place:
+
+```
+[debug] [github] request url: https://api.github.com/search/repositories?q=cli
+[error] [github] non-rate-limit 403: remaining=42 retry-after=60
+ x-ratelimit-reset=1790859999 authed=no url=…
+[error] [github] 403 body: {"message":"Resource not accessible by integration"}
+```
+
+Unset by default, so it costs nothing in normal use; token values are redacted
+from logged URLs.
+
+## The post-upgrade panel never went away
+
+The panel that says `Updated ghfind 9.8.3 → 9.9.0` is triggered by a single
+condition: `lastInstalledVersion !== currentVersion`. Nothing in the codebase
+ever wrote `lastInstalledVersion` back after showing the panel, so the
+condition stayed true forever:
+
+    launch 1 after upgrade:  panel shown
+    launch 2:               panel shown again
+    launch 3:               panel shown again
+    …
+
+Worse, dismissing it did not help. **later** writes `snoozeUntil` and **never**
+writes `suppressed` — neither touches `lastInstalledVersion`, and the
+post-upgrade panel's guard only checks `suppressed`. So a user who explicitly
+told ghfind to stop notifying them still got the panel on every launch.
+
+The panel now acknowledges itself once shown. Two guards keep that honest: a
+recorded version _newer_ than the running one is left alone (so a rolled-back
+install, or an update that landed mid-session, is still reported), and the
+write is best-effort so a read-only state dir cannot block the panel.
+
+Verified across a simulated six-launch sequence:
+
+    panel per launch: [true, false, false, false, false, false]
+
+## A prerelease was being advertised as an upgrade
+
+`isNewerVersion` prefers `Bun.semver` and falls back to hand-rolled comparison
+for Node and the compiled binaries. The fallback dropped the pre-release suffix
+but compared nothing else about it, so `9.9.0` → `9.9.0-beta.1` reported
+`true` — offering a **downgrade** as an update. Build metadata had a related
+bug: `9.9.0+build.5` parsed `Number("0+build")` as `NaN`, silently becoming
+`0`.
+
+Comparison now follows npm ordering. A prerelease counts as an upgrade only when
+its numeric core is genuinely ahead; within the same core, only a
+prerelease → release move counts; build metadata is stripped before parsing.
+The Bun path was already correct and is untouched.
+
+## `forks` was silently the wrong qualifier
+
+`KNOWN_QUALIFIERS` listed `fork` but not `forks`. So `forks:100` fell through
+to fuzzy matching, got rewritten to `fork:100`, and skipped numeric validation
+entirely — `forks:abc` validated clean and reached GitHub. `forks`, `topics`
+and `followers` are now known, and `fork` (a boolean) stays distinct from
+`forks` (a count).
+
+## A how-to guide
+
+`docs/HOW-TO.md` covers the task-shaped material the README does not: getting a
+token in place first (60/hr → 5,000/hr is the difference between a TUI session
+that works and one that dies mid-scroll), how to write a query, a qualifier
+table, what to read in the results, what to do about an error, and copy-paste
+recipes. Its claims are pinned by tests so the page cannot drift from the code.
+
+## Verification
+
+The suite grew by 110 tests: 82 for query parsing and validation, 2 pinning the
+403 diagnostics, 11 keeping the how-to page honest, and 15 on self-update. The
+new tests cover each qualifier value rule, `k`/`m` normalization and the
+exact-match guarantee, misspelling correction and unknown-qualifier
+passthrough, keyword-order and `raw` preservation, the relaxation ranking, the
+403 diagnostics — including that `remaining: 0` still routes to
+`RateLimitError` rather than `ForbiddenError` — and the update panel firing
+exactly once across repeated launches.
+
+`format:check`, `typecheck` (tsc) and `lint` (Biome) all green. Every example
+in the how-to was executed against the live API rather than written from memory.

package/src/cli.ts

@@ -6,6 +6,8 @@ import {
   rankRepos,
   createGitHubSearch,
   createTrendingSearch,
+  trendingQuery,
+  validateQuery,
 } from "./search";
 import {
   createPackageSearch,
@@ -645,6 +647,9 @@ interface SearchContext {
 
 function buildSearchContext(flags: CLIFlags): SearchContext {
   const parsed = applyFlagFilters(parseQuery(flags.query), {});
+  // Validate before the context is built so every handler (search, pipe,
+  // format, watch) inherits the same gate — previously only the TUI checked.
+  validateQuery(parsed);
   return {
     query: flags.query,
     parsed,
@@ -1154,17 +1159,14 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
       }
-      const response = await trendingSearch.search(
-        { keywords: [], qualifiers: [], raw: "trending" },
-        {
-          limit: 25,
-          sort: "stars",
-          json: false,
-          verbose: false,
-          trendingSince: since,
-          ...(language ? { trendingLanguage: language } : {}),
-        },
-      );
+      const response = await trendingSearch.search(trendingQuery(), {
+        limit: 25,
+        sort: "stars",
+        json: false,
+        verbose: false,
+        trendingSince: since,
+        ...(language ? { trendingLanguage: language } : {}),
+      });
       if (outputFormat) {
         console.log(formatOutput(response.repos, outputFormat));
       } else if (flags.count) {