github-search-cli 9.8.3 → 9.9.0

package/docs/HOW-TO.md

@@ -0,0 +1,254 @@
+# 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, `Space` opens the leader menu, 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,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.8.3",
+  "version": "9.9.0",
   "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",
@@ -21,6 +21,7 @@
     "src/",
     "scripts/",
     "completions/",
+    "docs/",
     "demo.svg",
     "LICENSE",
     "CHANGELOG.md",

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) {

package/src/errors.ts

@@ -34,15 +34,21 @@ export class AuthError extends SearchCliError {
 }
 
 /**
- * HTTP 403 — authenticated but not allowed (SAML enforcement, resource
- * restrictions, secondary limits). Not the same as the rate-limit 403,
- * which is detected by an exhausted x-ratelimit-remaining header first.
+ * HTTP 403 that is NOT a primary rate limit (i.e. `x-ratelimit-remaining`
+ * was greater than zero). Three unrelated causes land here and the status
+ * code cannot tell them apart:
+ *   - the token's org enforces SAML SSO and has not authorized it
+ *   - a secondary/abuse rate limit (concurrent or rapid-fire requests)
+ *   - a valid token blocked by org or resource restrictions
+ * The old message asserted SSO unconditionally, which sent people to fix a
+ * credential problem that did not exist. Check GHFIND_LOG for the body.
  */
 export class ForbiddenError extends SearchCliError {
-  constructor() {
+  constructor(public readonly detail: string = "GitHub API returned 403") {
     const msg =
-      "⚠ Forbidden (403). If your org enforces SSO, authorize the token; [t] to change it";
-    super("GitHub API returned 403 (token lacks access)", msg);
+      `⚠ Forbidden (403) — ${detail}. Common causes: org SSO not authorizing the token, ` +
+      `or a secondary rate limit. Press [t] to change the token`;
+    super(msg, msg);
     this.name = "ForbiddenError";
   }
 }
@@ -61,17 +67,35 @@ export class RateLimitError extends SearchCliError {
 }
 
 export class BadQueryError extends SearchCliError {
-  constructor(public readonly detail: string) {
-    super(`Invalid query: ${detail}`, `⚠ Invalid query: ${detail}`);
+  /** A concrete, corrected query the user can retry with. */
+  constructor(
+    public readonly detail: string,
+    public readonly hint?: string,
+  ) {
+    super(
+      `Invalid query: ${detail}`,
+      hint
+        ? `⚠ Invalid query: ${detail}\n  Try: ${hint}`
+        : `⚠ Invalid query: ${detail}`,
+    );
     this.name = "BadQueryError";
   }
 }
 
 export class NoResultsError extends SearchCliError {
-  constructor(public readonly query: string) {
+  /** Concrete loosened queries to retry, most promising first. */
+  constructor(
+    public readonly query: string,
+    public readonly relaxations: string[] = [],
+  ) {
+    const tips = relaxations.length
+      ? relaxations.map((r) => `Try: ${r}`).join("\n  ")
+      : "Tips: check spelling, try fewer qualifiers, or [b]rowse trending";
     super(
-      `No results for "${query}"`,
-      `🔍 No results for "${query}". Tips: check spelling, try fewer qualifiers, or [b]rowse trending`,
+      relaxations.length > 0
+        ? `No results for "${query}" — try loosening: ${relaxations.join(" / ")}`
+        : `No results for "${query}"`,
+      `🔍 No results for "${query}".\n  ${tips}`,
     );
     this.name = "NoResultsError";
   }

package/src/mcp-server.ts

@@ -29,6 +29,8 @@ import {
   createGitHubSearch,
   createTrendingSearch,
   resolveTrendingLanguage,
+  trendingQuery,
+  validateQuery,
 } from "./search";
 import {
   createPackageSearch,
@@ -55,7 +57,7 @@ import {
   type SkillSource,
 } from "./skill-finder";
 import { getVersion } from "./version";
-import { RateLimitError } from "./errors";
+import { RateLimitError, BadQueryError } from "./errors";
 
 // ─── Protocol constants ────────────────────────────────────────────────
 
@@ -215,7 +217,7 @@ function asMcpToolError(err: unknown): McpToolError {
   return new McpToolError(err instanceof Error ? err.message : String(err));
 }
 
-const TRENDING_QUERY = { keywords: [], qualifiers: [], raw: "trending" };
+const TRENDING_QUERY = trendingQuery();
 
 // ─── Tool registry ─────────────────────────────────────────────────────
 
@@ -271,6 +273,20 @@ const TOOLS: ToolDefinition[] = [
 
       const provider = createGitHubSearch(undefined, token ? [token] : []);
       const parsed = parseQuery(query);
+      // Reject a malformed qualifier here rather than spending an API call:
+      // for an agent, GitHub's opaque 422 reads as breakage, whereas the
+      // specific message names the bad token and the fix.
+      try {
+        validateQuery(parsed);
+      } catch (err) {
+        if (err instanceof BadQueryError) {
+          return {
+            text: `Invalid query: ${err.detail}${err.hint ? ` Try: ${err.hint}` : ""}`,
+            data: { totalCount: 0, repos: [], invalidQuery: true },
+          };
+        }
+        throw err;
+      }
       const options: SearchOptions = {
         limit,
         sort,

package/src/search-state.ts

@@ -14,6 +14,7 @@ import {
   createGitHubSearch,
   SearchModule,
   TrendingAdapter,
+  trendingQuery,
 } from "./search";
 import { restoreSession, saveSession } from "./session";
 import { appendHistory } from "./history";
@@ -155,16 +156,13 @@ export class SearchStateManager {
     this.state.trendingTab = tab;
     this.state.currentMode = "trending";
     try {
-      const response = await this.trendingSearch.search(
-        { keywords: [], qualifiers: [], raw: "trending" },
-        {
-          limit: 25,
-          sort: "stars",
-          json: false,
-          verbose: false,
-          trendingSince: tabSince(tab),
-        },
-      );
+      const response = await this.trendingSearch.search(trendingQuery(), {
+        limit: 25,
+        sort: "stars",
+        json: false,
+        verbose: false,
+        trendingSince: tabSince(tab),
+      });
       this.state.currentRepos = response.repos;
       this.state.totalCount = response.totalCount;
       appendHistory({