github-search-cli 9.8.2 → 9.9.0

package/CHANGELOG.md

@@ -6,6 +6,135 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
+## [9.9.0] — 2026-10-01 (released)
+
+### Added
+
+- **Queries are understood instead of passed through.** Every surface —
+  TUI, CLI, MCP, `--watch` — now parses and checks a query before spending an
+  API call, so a typo or a malformed value fails with a specific, actionable
+  message instead of an opaque 422 or a misleading "network error".
+  - Misspelled qualifiers are corrected: `langauge:Rust` → `language:Rust`,
+    `star:1000` → `stars:1000`, `push:>2024-01-01` → `pushed:>2024-01-01`.
+    Correction is scoped to the qualifiers ghfind knows, so a qualifier it has
+    never heard of (`is:`, `has:`, `props.*`) is passed through untouched
+    rather than mangled into something else.
+  - Counts accept `k`/`m` sugar: `stars:10k` → `stars:>=10000`,
+    `size:1m` → `size:>=1000000`, `stars:1k..10k` → `stars:1000..10000`.
+    A bare count keeps GitHub's exact-match meaning — `stars:100` still means
+    exactly 100.
+  - Values are validated per qualifier: numeric counts, `fork:true|false|only`,
+    `archived:true|false`, ISO8601 dates for `created`/`pushed`/`updated`,
+    the `visibility:` enum, and the `in:` searchable fields. An invalid value
+    reports the bad token and the fix, e.g. `⚠ Invalid query: "stars:abc" is
+not a number — use stars:100, stars:>=100, or stars:1k..10k`.
+  - `validateQuery` is now called by the CLI, the MCP server and `--watch`, not
+    just the TUI. Previously only the TUI enforced the one existing rule.
+- **Zero-result searches now suggest how to loosen the query.** Qualifiers are
+  ranked by how sharply they narrow results — a star or size threshold empties
+  a result set outright, so those are loosened first — and each suggestion
+  rewrites one qualifier rather than dropping it: `No results for "rust
+stars:>=5000000"` now offers `Try: rust stars:>=500000`.
+- **`GHFIND_LOG=<path>` writes TUI diagnostics to a file.** The TUI owns the
+  screen and cannot print diagnostics into it, and its logger was previously a
+  silent no-op — which made API failures undiagnosable. Token values are
+  redacted from logged URLs. Unset by default, so there is no cost in normal
+  use.
+- **`docs/HOW-TO.md`** — a task-oriented guide: setting up a token, writing
+  queries, reading results, and what to do when a search returns nothing or an
+  error appears.
+
+### Fixed
+
+- **A forbidden response no longer claims SSO is the cause.** Three unrelated
+  conditions return 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 SSO case unconditionally, sending people to fix
+  a credential problem that did not exist. The message now reports GitHub's
+  own reason and names both plausible causes; the response headers and body
+  (which identify the real one) are written to `GHFIND_LOG`.
+- **`forks` is recognised as a qualifier.** Only `fork` was listed, so
+  `forks:100` was fuzzy-matched into `fork:100` and lost its numeric
+  validation. `forks`, `topics` and `followers` are now known too, and
+  `fork` (boolean) stays distinct from `forks` (count).
+- **Custom-property qualifiers are no longer misread as keywords.**
+  `props.environment:production` contains a dot, which the parser rejected, so
+  it silently became a literal search term instead of a qualifier.
+- **`--watch` fails fast on a malformed query** instead of retrying the same
+  non-transient error five times.
+- **The post-upgrade panel no longer reappears on every launch.** It is
+  triggered by `lastInstalledVersion !== currentVersion`, and nothing ever
+  cleared `lastInstalledVersion` — so after one upgrade the "Updated ghfind
+  X → Y" panel showed again on every single launch, including after dismissing
+  it with **later** or **never** (neither touched that field). The panel now
+  acknowledges itself when shown. A recorded version _newer_ than the running
+  one is deliberately left alone, so a rollback or a mid-session update is
+  still reported.
+- **A prerelease is no longer offered as an upgrade.** The Node/compiled
+  fallback in the version comparison treated `9.9.0-beta.1` as newer than
+  `9.9.0` — advertising a downgrade. Comparison now follows npm ordering: a
+  prerelease counts only when its numeric core is genuinely ahead, and build
+  metadata (`+build.5`) is ignored rather than corrupting the parse.
+
+---
+
+## [9.8.3] — 2026-10-01 (released)
+
+### Fixed
+
+- **The TUI always opens on the landing menu again.** A saved session used to
+  skip it on every launch, and one user's session had an MCP handshake request
+  saved as its query, so startup auto-ran a garbage search instead of showing
+  the menu. Sessions now restore preferences and pre-fill the last query only
+  when a mode is picked; they never auto-run a search. Both save and restore
+  sanitize the session: JSON-shaped or oversized queries are dropped, and
+  malformed fields fall back to defaults, so a corrupted file can't hijack
+  startup again.
+- **401/403 API errors now say what actually went wrong instead of "Network
+  error".** A rejected token (401) shows "Bad GitHub token (401)" with keys to
+  fix it; an authenticated-but-forbidden 403 (e.g. SAML/SSO enforcement) names
+  the SSO case; only genuine connectivity/server failures keep the generic
+  network message. A rate-limited search no longer swallows the error and
+  renders as a silent zero-result "success" — the real message reaches the
+  status bar, the MCP server reports it as structured backoff advice, and the
+  adapter no longer turns rate limits into empty results.
+- **Recover-from-errors without leaving the TUI.** While the matching error is
+  showing, `t` opens an inline token prompt (saves to config and re-runs the
+  failed query), `u` clears the token and retries unauthenticated, `c` swaps in
+  a different token after a rate limit, and `r` retries. Documented in the help
+  overlay and README.
+- **An image wrapped in a link now renders.** The badge-and-screenshot shape
+  `[![alt](shot.png)](url)` — used by `sst/opencode` (its only hero image was
+  lost) and `withastro/astro` (23 of 25 images lost) — was treated as prose
+  because the markdown token walk rejected `link` tokens instead of recursing
+  into them. The image now renders and keeps its link as an OSC 8 hyperlink on
+  the image cells, so clicking it in the terminal opens the same URL.
+- **A README full of small images no longer floods the screen.** Images whose
+  README declares an edge under 100 px (`<img width="48">` sponsor avatars,
+  badges) are filtered while parsing, before any request is made; images with
+  no declared size are measured from their header after the download
+  (`Bun.Image.metadata()`, header read only — no pixel decode) and rejected
+  before rasterising. On `openclaw/openclaw` (661 `<img>` tags, 648 of them
+  48×48 avatars) this takes the README from 649 downloads / 28.3 s to open to
+  1 download / ~0.5 s.
+- A pure-image block whose refs are all filtered out renders as nothing instead
+  of falling back to prose, which would have printed the raw markdown of the
+  filtered-out image.
+
+### Changed
+
+- **Images smaller than 100 px on any edge are no longer rendered, even when
+  the declared size understates the real one** (two images in
+  `openclaw/openclaw` declare `width="48"` but are 420×420). The README is
+  treated as the authority on size; the alternative — rendering the avatar at
+  whatever the terminal fits — is what made these READMEs unusable.
+- The TUI no longer skips the landing menu on startup: a saved session
+  restores sort/limit/trending tab and pre-fills the query when you pick Repo
+  Search, but the menu always comes first. See the session-sanitizing fix
+  above.
+
+---
+
 ## [9.8.2] — 2026-09-28 (released)
 
 ### Security

package/README.md

@@ -224,6 +224,15 @@ ghfind --completion fish | source
 | `Esc`                 | Close current overlay                          |
 | `q`                   | Quit ghfind                                    |
 
+**Error recovery** — active only while the matching error is in the status bar
+
+| Key | Action                                        |
+| --- | --------------------------------------------- |
+| `r` | Retry the failed search / trending load       |
+| `t` | Fix the GitHub token (401 bad token, 403 SSO) |
+| `u` | Search without a token (401)                  |
+| `c` | Change token (rate limit)                     |
+
 **Leader menu** — press `Space`, navigate with `↑`/`↓`, press `Enter` to dispatch
 
 Actions shown depend on current mode (search vs trending) and selection:
@@ -283,7 +292,22 @@ topic:cli -language:JavaScript
 org:rust-lang language:Rust
 ```
 
-Prefix with `-` to exclude. Supported: `language`, `stars`, `fork`, `archived`, `topic`, `user`, `org`, `repo`, `updated`, `pushed`, `visibility`, `license`, `created`, `size`, `in`.
+Prefix with `-` to exclude. Supported: `language`, `stars`, `forks`, `topics`, `followers`, `size`, `fork`, `archived`, `topic`, `user`, `org`, `repo`, `updated`, `pushed`, `visibility`, `license`, `created`, `in`.
+
+Queries are parsed and checked before the request is sent:
+
+- **Qualifier typos are corrected** — `langauge:Rust` → `language:Rust`,
+  `star:1000` → `stars:1000`. Correction is limited to the qualifiers listed
+  above, so `is:`, `has:` and `props.*` pass through untouched.
+- **Counts accept `k`/`m`** — `stars:10k` means 10,000 or more. A bare count
+  keeps GitHub's exact-match meaning, so use `stars:>=100` or `stars:10k`
+  rather than `stars:100`.
+- **An invalid value is rejected with the fix**, not sent to GitHub:
+  `⚠ Invalid query: "stars:abc" is not a number — use stars:100, stars:>=100, or stars:1k..10k`
+- **An empty result suggests how to loosen the query** — qualifiers are ranked
+  by how sharply they narrow results, and the message offers a concrete retry.
+
+See [docs/HOW-TO.md](docs/HOW-TO.md) for a task-oriented walkthrough.
 
 ---
 
@@ -300,7 +324,7 @@ Prefix with `-` to exclude. Supported: `language`, `stars`, `fork`, `archived`,
 }
 ```
 
-Env: `GITHUB_TOKEN`, `GHFIND_CONFIG`, `GHFIND_SKILL_ROOTS` (path-separator separated skill directories for `ghfind skill search`), `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `NO_COLOR` (disables colored `--doctor` output, per [no-color.org](https://no-color.org/))
+Env: `GITHUB_TOKEN`, `GHFIND_CONFIG`, `GHFIND_LOG` (path — write TUI diagnostics there; unset by default), `GHFIND_SKILL_ROOTS` (path-separator separated skill directories for `ghfind skill search`), `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `NO_COLOR` (disables colored `--doctor` output, per [no-color.org](https://no-color.org/))
 
 ---
 
@@ -313,14 +337,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 482 tests
+bun test         # 624 tests
 bun run check    # format check + tests — the green gate
 bun run build    # build dist/
 
 # Or with npm
 npm install
 npm start        # TUI (requires Node 20+)
-npm test         # 414 tests
+npm test         # 624 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -331,23 +355,22 @@ npm run build    # build dist/
 
 ## Known limitations
 
-**README image rendering is currently incomplete.** Images that do render look
-right, but several common cases silently show nothing:
-
-- **An image wrapped in a link does not render at all.** This is the common
-  badge-and-screenshot style: `[![alt](shot.png)](https://example.com)`.
-  The whole block is treated as prose and the image is dropped.
-- **An image smaller than 100px is skipped**, judged by the `width`/`height`
-  the README declares in its `<img>` tag. A README that understates an
-  image's size hides that image.
-- **SVG is not rendered** — the rasteriser cannot draw it.
-- Markdown `![](url)` images have no declared size, so they are downloaded
-  before the size check can reject them. A README full of them is slow to open.
-
-A README using none of the above — plain `![]()` images and a few large
-banners — renders fine and fast. See
+README image rendering has one deliberate blind spot and one hard one:
+
+- **Images smaller than 100 px on any edge are skipped.** For `<img>` tags the
+  declared `width`/`height` is trusted, so an image that understates its size
+  is hidden (a README that _overstates_ nothing is never affected). Markdown
+  `![]()` images declare no size, so they are measured from the image header
+  instead — still before any pixels are decoded.
+- **SVG is not rendered** — the rasteriser cannot draw it, so SVGs (and
+  badge-service images, which are tiny SVGs with text baked in) show an
+  `🖼 alt` caption instead.
+
+An image wrapped in a link — `[![alt](shot.png)](url)`, the badge-and-screenshot
+style — renders fine and keeps its link: the image cells carry an OSC 8
+hyperlink, so clicking it opens the target in your browser. See
 [.issues/tickets/readme-image-rendering.md](.issues/tickets/readme-image-rendering.md)
-for the measurements and the remaining work.
+for the architecture, measurements, and remaining work.
 
 ---
 
@@ -355,6 +378,28 @@ for the measurements and the remaining work.
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
+### v9.9.0
+
+- **Queries are understood before they are sent** — every surface (TUI, CLI, MCP, `--watch`) parses and checks a query first, so a typo or bad value fails with a specific message and a fix instead of an opaque GitHub 422 or a misleading "network error"; previously only the TUI ran validation at all
+- **Qualifier typos are corrected** — `langauge:Rust` → `language:Rust`, `star:1000` → `stars:1000`, `push:>` → `pushed:>`; correction is limited to the qualifiers ghfind knows, so `is:`, `has:` and `props.*` are never mangled
+- **Counts accept `k`/`m`** — `stars:10k` → `stars:>=10000`, `size:1m`, `stars:1k..10k`; a bare count keeps GitHub's exact-match meaning, so `stars:100` is still exactly 100
+- **Values are validated per qualifier** — numeric counts, `fork:true|false|only`, `archived:true|false`, calendar-checked ISO8601 dates for `created`/`pushed`/`updated`, the `visibility:` enum, and `in:` fields; documented comma-lists like `in:name,description` still work
+- **Zero results suggest how to loosen the query** — `No results for "rust stars:>=5000000"` now offers `Try: rust stars:>=500000`, ranked by how sharply each qualifier narrows results
+- **`GHFIND_LOG=<path>` writes TUI diagnostics to a file** — the TUI's logger was a silent no-op, making API failures undiagnosable; token values are redacted from logged URLs
+- **A 403 no longer claims SSO is the cause** — SSO enforcement, secondary rate limits and org restrictions all produce it, and the message asserted the first one unconditionally; it now reports GitHub's own reason
+- **The post-upgrade panel no longer reappears on every launch** — it was triggered by a version inequality nothing ever cleared, so it showed after every single launch _including_ after "later" or "never"; it now acknowledges itself once shown
+- **A prerelease is no longer offered as an upgrade** — the version comparison used by Node and the compiled binaries reported `9.9.0-beta.1` as newer than `9.9.0`, i.e. a downgrade; it now follows npm ordering and ignores build metadata
+- **A new [how-to guide](docs/HOW-TO.md)** — token setup, writing queries, reading results, recovering from errors, and copy-paste recipes
+
+### v9.8.3
+
+- **401/403 say what actually happened** — a rejected token and an authenticated-but-forbidden request (e.g. SAML/SSO enforcement) both used to report "Network error", naming a connectivity problem you didn't have; only genuine connectivity and server failures keep that message now
+- **A rate-limited search no longer looks like an empty one** — the adapter used to swallow the error and render a silent, successful "no repositories found"; the real message reaches the status bar, and the `ghfind_search_repos` MCP tool returns `rateLimited: true` with backoff advice instead of a tool failure
+- **Recover from errors without leaving the TUI** — while the matching error is in the status bar, `t` opens an inline token prompt (saves it and re-runs the failed query), `u` clears the token and retries unauthenticated, `c` swaps in a different token, `r` retries
+- **A corrupted session no longer hijacks startup** — a `session.json` holding an MCP handshake blob used to skip the landing menu and auto-run that garbage as a search on every launch; the menu always comes first now, and both save and restore sanitize the session
+- **Images wrapped in a link render now** — the badge-and-screenshot shape `[![alt](shot.png)](url)` rendered nothing at all, which cost `sst/opencode` its only image and `withastro/astro` 23 of its 25; the image cells carry an OSC 8 hyperlink, so clicking it opens the target
+- **A README full of small images no longer floods the screen** — images the README declares under 100px on any edge are skipped before a request is made, and undeclared `![]()` images are measured from the image header before any pixel decode; on `openclaw/openclaw` (648 sponsor avatars) that is 649 fetches / 28.3s → 1 fetch / ~0.5s
+
 ### v9.8.2
 
 - **Security: tokens no longer leak into crash reports** — an uncaught error auto-built a GitHub issue URL from raw `process.argv`, so a `--token` value ended up in a public URL; every field is redacted now, and ghfind prints the URL to copy instead of opening a browser when it finds a credential
@@ -380,12 +425,6 @@ Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
   [Known limitations](#known-limitations); the v9.8.0 notes wrongly described it
   as working
 
-### v9.8.0
-
-- **README viewer renders real markdown** — headings, emphasis, links, lists, blockquotes, boxed tables, and fenced code now come from OpenTUI's markdown renderable with a theme-derived syntax style instead of a box-drawing text approximation
-- **Images render inline — see [Known limitations](#known-limitations)** — relative and `/`-rooted paths resolve against the README's branch, `github.com/.../blob/...` links are rewritten to raw content, downloads are cached and size-capped, SVG and badge-service images are skipped, and anything unloadable falls back to an `🖼 alt` caption; press `i` in the viewer to toggle images
-- **No new dependencies** — the PNG decoder, image-to-cells rasteriser, and fetch cache are plain TypeScript, and images draw with truecolor half blocks, so they work on any truecolor terminal without image-protocol support
-
 ## License
 
 MIT