github-search-cli 9.8.1 → 9.8.3

package/CHANGELOG.md

@@ -6,6 +6,126 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
+## [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
+
+- **GitHub tokens no longer leak into crash reports.** An uncaught error
+  auto-built a GitHub issue URL from the raw `process.argv`, so a token passed
+  as `--token` ended up in a public URL. Every field is now redacted before it
+  reaches the URL, title, body or stack trace, and when a credential is
+  detected ghfind prints the URL to copy instead of opening a browser.
+- **Your token is never sent to `raw.githubusercontent.com`** when fetching a
+  README. It is only attached to `api.github.com` requests, and only for a
+  repository marked private.
+- **Untrusted skill sources are validated** before they can reach a shell
+  command or URL. A `source` or `skillId` containing shell metacharacters
+  (`;`, `$`, backticks, newlines, path traversal) is now dropped from
+  registry results instead of being interpolated into `npx skills add`.
+- **The config file holding your token is written with `0600` permissions**
+  (effective on POSIX; on Windows the file still inherits the directory ACL).
+- `--doctor` masks the token with `maskToken()` instead of printing a
+  raw 7-character prefix.
+
+### Fixed
+
+- **Recoverable errors no longer open a bug-report tab.** The catch in
+  `src/cli.ts` tested `err.name === "SearchCliError"`, which is never true
+  because each subclass sets its own name, so rate-limit, network and
+  layout-change errors all fell through to the crash reporter. Routing now uses
+  `instanceof SearchCliError`.
+- **`--compare` and the MCP tool `ghfind_compare_repos` resolve repos
+  exactly.** Both used a free-text search with no `repo:` qualifier and never
+  checked the returned `fullName`, so they could silently compare a different
+  repository. They now use the existing `resolveRepoFromRef()` seam
+  (`GET /repos/{owner}/{repo}`).
+- **State files are written atomically.** Bookmarks, history, sessions, saved
+  searches, notifications and the update check were written straight to their
+  live path; a crash or a full disk left a truncated JSON file that was then
+  silently replaced with defaults, destroying user data. Writes now go to a
+  temp file and are renamed into place.
+- **Notification IDs no longer restart** after "dismiss all" — the id counter
+  was recomputed from an already-empty list.
+- **`ghfind history --delete` no longer removes every duplicate entry.** The
+  delete matched by value instead of by index.
+- **An invalid `--sort` value is rejected** with the list of valid choices and
+  a non-zero exit code instead of silently degrading to the default.
+- **A failed "load more" in the TUI no longer clears the results** already on
+  screen; the error goes to the status bar.
+- **`--markdown` escapes `|` in cells**, matching `--csv`.
+- Local skill scanning is memoised per process, so a search no longer re-walks
+  the skill roots on every keystroke.
+- `MemoryCache.set` is a true LRU — a refreshed entry now moves to the end of
+  the insertion order.
+- Skill ids and sources may contain `_` (e.g. `my_org/my_repo`), which
+  are common on GitHub and were wrongly rejected.
+
+### Changed
+
+- **`postinstall` and the bundled agent skill are unchanged in behaviour**; the
+  skill now states that `--compare` resolves a repository exactly.
+- Internal `--compare` resolution is now shared by the CLI and the MCP server
+  instead of duplicated in both.
+
+---
+
 ## [9.8.1] — 2026-09-26 (released)
 
 ### Added

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 search-cli contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 search-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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:
@@ -313,14 +322,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 414 tests
+bun test         # 516 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         # 516 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -331,23 +340,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 +363,25 @@ for the measurements and the remaining work.
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
+### 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
+- **Security: your token is never sent to `raw.githubusercontent.com`** when fetching a README, only to `api.github.com` and only for a private repo
+- **Security: untrusted skill sources are validated** before reaching a shell command or URL, so a hostile skills.sh entry cannot inject into `npx skills add`
+- **Recoverable errors no longer open a bug-report tab** — rate limits, network blips and layout changes print a short message and exit
+- **`--compare` resolves repositories exactly** in both the CLI and the `ghfind_compare_repos` MCP tool; it used a free-text search that could silently compare the wrong repo
+- **State files are written atomically** — a crash mid-write used to leave truncated JSON that was silently replaced with defaults, losing bookmarks and history
+- Fixed notification IDs restarting after "dismiss all", `history --delete` removing every duplicate, an invalid `--sort` degrading silently, a failed "load more" clearing the TUI's results, `--markdown` not escaping `|`, and a not-quite-LRU memory cache
+
 ### v9.8.1
 
 - **`ghfind skill search <query>`** finds agent skills by keyword and prints why
@@ -376,13 +403,6 @@ Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 - **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
 
-### v9.7.1
-
-- **In-app update actually works now** — it used to `bun install -g` into `~/.bun` while your running copy lives in an npm prefix, reporting success while nothing changed; it now detects which package manager owns the running install and updates it in place
-- **New `ghfind --doctor` check** — flags stale/PATH-shadowing global installs (multiple `ghfind` copies with different versions) and prints the exact uninstall command
-- **Windows URL fix** — links with query params were truncated at the first `&` by `cmd /c start`; every pre-filled crash-report/issue link now opens complete
-- Fixed `open-url` crashing under Node; CI now enforces lint + typecheck gates (first green Biome baseline)
-
 ## License
 
 MIT

package/completions/ghfind.bash

@@ -1,55 +1,55 @@
-# ghfind bash completion
-# Source: source <(ghfind --completion bash)
-
-_ghfind() {
-  local cur prev opts
-  COMPREPLY=()
-  cur="${COMP_WORDS[COMP_CWORD]}"
-  prev="${COMP_WORDS[COMP_CWORD-1]}"
-
-  opts="--json --csv --markdown --count --limit --sort --token --trending --language --since --pipe --format --registry --watch --interval --version --help --completion --remote --local --copy --raw --as pkg login init doctor org user mcp skill bookmarks history topics saved readme share trending deep-dive compare"
-
-  case "${prev}" in
-    --sort)
-      COMPREPLY=( $(compgen -W "best-match stars updated forks" -- "${cur}") )
-      return 0
-      ;;
-    --since)
-      COMPREPLY=( $(compgen -W "daily weekly monthly" -- "${cur}") )
-      return 0
-      ;;
-    --pipe)
-      COMPREPLY=( $(compgen -W "clone open" -- "${cur}") )
-      return 0
-      ;;
-    --format)
-      COMPREPLY=( $(compgen -W "urls names ssh-urls clone-commands ids" -- "${cur}") )
-      return 0
-      ;;
-    --completion)
-      COMPREPLY=( $(compgen -W "bash zsh fish" -- "${cur}") )
-      return 0
-      ;;
-    --as)
-      COMPREPLY=( $(compgen -W "markdown plain gh-cli short" -- "${cur}") )
-      return 0
-      ;;
-    --registry)
-      COMPREPLY=( $(compgen -W "npm" -- "${cur}") )
-      return 0
-      ;;
-    --language)
-      COMPREPLY=( $(compgen -W "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig" -- "${cur}") )
-      return 0
-      ;;
-    --limit|--interval)
-      return 0
-      ;;
-    *)
-      ;;
-  esac
-
-  COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
-  return 0
-}
-complete -F _ghfind ghfind
+# ghfind bash completion
+# Source: source <(ghfind --completion bash)
+
+_ghfind() {
+  local cur prev opts
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  opts="--json --csv --markdown --count --limit --sort --token --trending --language --since --pipe --format --registry --watch --interval --version --help --completion --remote --local --copy --raw --as pkg login init doctor org user mcp skill bookmarks history topics saved readme share trending deep-dive compare"
+
+  case "${prev}" in
+    --sort)
+      COMPREPLY=( $(compgen -W "best-match stars updated forks" -- "${cur}") )
+      return 0
+      ;;
+    --since)
+      COMPREPLY=( $(compgen -W "daily weekly monthly" -- "${cur}") )
+      return 0
+      ;;
+    --pipe)
+      COMPREPLY=( $(compgen -W "clone open" -- "${cur}") )
+      return 0
+      ;;
+    --format)
+      COMPREPLY=( $(compgen -W "urls names ssh-urls clone-commands ids" -- "${cur}") )
+      return 0
+      ;;
+    --completion)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "${cur}") )
+      return 0
+      ;;
+    --as)
+      COMPREPLY=( $(compgen -W "markdown plain gh-cli short" -- "${cur}") )
+      return 0
+      ;;
+    --registry)
+      COMPREPLY=( $(compgen -W "npm" -- "${cur}") )
+      return 0
+      ;;
+    --language)
+      COMPREPLY=( $(compgen -W "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig" -- "${cur}") )
+      return 0
+      ;;
+    --limit|--interval)
+      return 0
+      ;;
+    *)
+      ;;
+  esac
+
+  COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+  return 0
+}
+complete -F _ghfind ghfind

package/completions/ghfind.fish

@@ -1,29 +1,29 @@
-# ghfind fish completion
-# Source: source (ghfind --completion fish | psub)
-
-complete -c ghfind -l json -d "JSON output"
-complete -c ghfind -l csv -d "CSV output"
-complete -c ghfind -l markdown -d "Markdown table output"
-complete -c ghfind -l count -d "Only result count"
-complete -c ghfind -l limit -d "Max results" -r
-complete -c ghfind -l sort -d "Sort strategy" -r -f -a "best-match stars updated forks"
-complete -c ghfind -l token -d "GitHub token" -r
-complete -c ghfind -l trending -d "Trending mode"
-complete -c ghfind -l language -d "Trending language filter" -r -f -a "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig"
-complete -c ghfind -l since -d "Trending period" -r -f -a "daily weekly monthly"
-complete -c ghfind -l pipe -d "Pipe target" -r -f -a "clone open"
-complete -c ghfind -l format -d "Output format" -r -f -a "urls names ssh-urls clone-commands ids"
-complete -c ghfind -l registry -d "Registry for pkg" -r -f -a "npm"
-
-complete -c ghfind -l watch -d "Watch mode"
-complete -c ghfind -l interval -d "Watch interval seconds" -r
-complete -c ghfind -l version -d "Print version"
-complete -c ghfind -l help -d "Print help"
-complete -c ghfind -l completion -d "Shell" -r -f -a "bash zsh fish"
-complete -c ghfind -l as -d "Share format" -r -f -a "markdown plain gh-cli short"
-complete -c ghfind -l remote -d "Skill search: query skills.sh instead of this machine"
-complete -c ghfind -l local -d "Skill search: force the local scan (default)"
-complete -c ghfind -l copy -d "Share: also copy the snippet to the clipboard"
-complete -c ghfind -l raw -d "Readme: print the raw markdown with no header"
-
+# ghfind fish completion
+# Source: source (ghfind --completion fish | psub)
+
+complete -c ghfind -l json -d "JSON output"
+complete -c ghfind -l csv -d "CSV output"
+complete -c ghfind -l markdown -d "Markdown table output"
+complete -c ghfind -l count -d "Only result count"
+complete -c ghfind -l limit -d "Max results" -r
+complete -c ghfind -l sort -d "Sort strategy" -r -f -a "best-match stars updated forks"
+complete -c ghfind -l token -d "GitHub token" -r
+complete -c ghfind -l trending -d "Trending mode"
+complete -c ghfind -l language -d "Trending language filter" -r -f -a "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig"
+complete -c ghfind -l since -d "Trending period" -r -f -a "daily weekly monthly"
+complete -c ghfind -l pipe -d "Pipe target" -r -f -a "clone open"
+complete -c ghfind -l format -d "Output format" -r -f -a "urls names ssh-urls clone-commands ids"
+complete -c ghfind -l registry -d "Registry for pkg" -r -f -a "npm"
+
+complete -c ghfind -l watch -d "Watch mode"
+complete -c ghfind -l interval -d "Watch interval seconds" -r
+complete -c ghfind -l version -d "Print version"
+complete -c ghfind -l help -d "Print help"
+complete -c ghfind -l completion -d "Shell" -r -f -a "bash zsh fish"
+complete -c ghfind -l as -d "Share format" -r -f -a "markdown plain gh-cli short"
+complete -c ghfind -l remote -d "Skill search: query skills.sh instead of this machine"
+complete -c ghfind -l local -d "Skill search: force the local scan (default)"
+complete -c ghfind -l copy -d "Share: also copy the snippet to the clipboard"
+complete -c ghfind -l raw -d "Readme: print the raw markdown with no header"
+
 complete -c ghfind -f -a "login init doctor org user bookmarks history topics saved readme share pkg mcp skill trending deep-dive compare"

package/completions/ghfind.zsh

@@ -1,53 +1,53 @@
-# ghfind zsh completion
-# Source: source <(ghfind --completion zsh)
-
-_ghfind() {
-  local -a opts
-  opts=(
-    '--json[JSON output]'
-    '--csv[CSV output]'
-    '--markdown[Markdown table output]'
-    '--count[Only result count]'
-    '--limit[Max results]:limit:'
-    '--sort[Sort strategy]:(best-match stars updated forks)'
-    '--token[GitHub token]:token:'
-    '--trending[Trending mode]'
-    '--language[Trending language filter]:language:'
-    '--since[Trending period]:(daily weekly monthly)'
-    '--pipe[Pipe target]:(clone open)'
-    '--format[Output format]:(urls names ssh-urls clone-commands ids)'
-    '--registry[Registry for pkg]:(npm)'
-
-    '--watch[Watch mode]'
-    '--interval[Watch interval seconds]:seconds:'
-    '--version[Print version]'
-    '--help[Print help]'
-    '--completion[Shell]:(bash zsh fish)'
-    '--as[Share format]:(markdown plain gh-cli short)'
-    '--remote[Skill search: query skills.sh instead of this machine]'
-    '--local[Skill search: force the local scan (default)]'
-    '--copy[Share: also copy the snippet to the clipboard]'
-    '--raw[Readme: print the raw markdown with no header]'
-
-    'login[Import a GitHub token from the gh CLI or paste one]'
-    'init[Run the setup wizard]'
-    'doctor[Environment diagnostics]'
-    'org[Org profile]:org name:'
-    'user[User profile]:user name:'
-    'bookmarks[List saved repos]:query:'
-    'history[List past searches]:query:'
-    'topics[Browse popular GitHub topics]'
-    'saved[List saved searches]'
-    'readme[Print a repository README]:owner/repo:'
-    'share[Print a share snippet]:owner/repo:'
-    'pkg[Search packages]:query:'
-    'trending[Trending repos, optionally by language]'
-    'deep-dive[Repo deep-dive: languages, contributors, README]:owner/repo:'
-    'mcp[Run the MCP server for AI agents (stdio)]'
-    'skill[Print an agent skill guide, or search with: skill search <query>]:skill name:'
-    'compare[Compare repositories]'
-  )
-  _arguments "${opts[@]}" '*:query:'
-}
-
+# ghfind zsh completion
+# Source: source <(ghfind --completion zsh)
+
+_ghfind() {
+  local -a opts
+  opts=(
+    '--json[JSON output]'
+    '--csv[CSV output]'
+    '--markdown[Markdown table output]'
+    '--count[Only result count]'
+    '--limit[Max results]:limit:'
+    '--sort[Sort strategy]:(best-match stars updated forks)'
+    '--token[GitHub token]:token:'
+    '--trending[Trending mode]'
+    '--language[Trending language filter]:language:'
+    '--since[Trending period]:(daily weekly monthly)'
+    '--pipe[Pipe target]:(clone open)'
+    '--format[Output format]:(urls names ssh-urls clone-commands ids)'
+    '--registry[Registry for pkg]:(npm)'
+
+    '--watch[Watch mode]'
+    '--interval[Watch interval seconds]:seconds:'
+    '--version[Print version]'
+    '--help[Print help]'
+    '--completion[Shell]:(bash zsh fish)'
+    '--as[Share format]:(markdown plain gh-cli short)'
+    '--remote[Skill search: query skills.sh instead of this machine]'
+    '--local[Skill search: force the local scan (default)]'
+    '--copy[Share: also copy the snippet to the clipboard]'
+    '--raw[Readme: print the raw markdown with no header]'
+
+    'login[Import a GitHub token from the gh CLI or paste one]'
+    'init[Run the setup wizard]'
+    'doctor[Environment diagnostics]'
+    'org[Org profile]:org name:'
+    'user[User profile]:user name:'
+    'bookmarks[List saved repos]:query:'
+    'history[List past searches]:query:'
+    'topics[Browse popular GitHub topics]'
+    'saved[List saved searches]'
+    'readme[Print a repository README]:owner/repo:'
+    'share[Print a share snippet]:owner/repo:'
+    'pkg[Search packages]:query:'
+    'trending[Trending repos, optionally by language]'
+    'deep-dive[Repo deep-dive: languages, contributors, README]:owner/repo:'
+    'mcp[Run the MCP server for AI agents (stdio)]'
+    'skill[Print an agent skill guide, or search with: skill search <query>]:skill name:'
+    'compare[Compare repositories]'
+  )
+  _arguments "${opts[@]}" '*:query:'
+}
+
 compdef _ghfind ghfind