github-search-cli 9.7.1 → 9.8.1

package/CHANGELOG.md

@@ -6,6 +6,86 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
+## [9.8.1] — 2026-09-26 (released)
+
+### Added
+
+- **`ghfind skill search <query>`** finds agent skills by keyword and prints
+  why each one matched. The default scan reads `SKILL.md` files under
+  `~/.codex/skills`, `~/.agents/skills`, `<project>/.codex/skills` and
+  `<project>/.github/skills`, in that priority order and de-duplicated by name
+  (the user-level roots overlap heavily on real machines). `--remote` queries
+  the public [skills.sh](https://skills.sh) ecosystem instead and returns each
+  hit's install count and `npx skills add` command. `GHFIND_SKILL_ROOTS`
+  overrides which directories are scanned.
+- **MCP tool `ghfind_skill_search`.** Agents can search skills the moment they
+  connect: `source: "local"` (the default) searches installed skills,
+  `source: "registry"` searches skills.sh. Read-only — it returns install
+  commands rather than running them, and never writes to disk.
+- **Read-only CLI views of local state:** `ghfind bookmarks [query]`,
+  `ghfind history [query]`, `ghfind saved` and `ghfind topics`, each with
+  `--json` for agents. They print what the TUI has stored and never modify it.
+- **`ghfind readme <owner/repo>`** prints a repository's README (`--raw` skips
+  the header, `--json` returns `{ owner, name, sourceUrl, text }`), bringing the
+  TUI's README viewer to scripts and agents.
+- **`ghfind share <owner/repo>`** prints a share snippet
+  (`--as markdown|plain|gh-cli|short`), with `--copy` to also put it on the
+  clipboard.
+- Shell completions (bash, zsh, fish) cover every new subcommand and flag.
+
+### Changed
+
+- The bundled `ghfind-cli` agent skill documents the skill search and the new
+  read-only commands, so CLI-first agents discover them without reading
+  `--help`.
+
+### Fixed
+
+- **README image rendering does not work on real repositories.** The v9.8.0
+  notes described inline images as working; that was wrong. An image wrapped
+  in a link (`[![alt](shot.png)](url)`) renders nothing, and a README with
+  many small images — `openclaw/openclaw` has 648 48x48 avatars — becomes
+  15,552 rows tall. Images declaring an edge under 100px are skipped, and
+  SVG is not rendered at all. Plain `![]()` images and large banners do
+  render correctly. Root causes and remaining work:
+  `.issues/tickets/readme-image-rendering.md`.
+
+---
+
+## [9.8.0] — 2026-09-22 (released)
+
+### Added
+
+- **README viewer now renders full markdown, including inline images.** The
+  viewer used to approximate markdown with box-drawing text; it now drives
+  OpenTUI's `MarkdownRenderable` with a theme-derived syntax style, so
+  headings, emphasis, links, lists, blockquotes, boxed tables, and fenced
+  code blocks render as markdown rather than as decorated plain text.
+- **Images in READMEs render in the terminal.** Relative and root-relative
+  paths resolve against the branch the README was loaded from,
+  `github.com/.../blob/...` links are rewritten to raw content, and downloads
+  are cached and capped by size. SVG and badge-service images are skipped
+  (they carry text that survives rasterising poorly), and anything that fails
+  to load falls back to an `🖼 alt text` caption. Images are drawn with
+  truecolor half blocks, so they work on any truecolor terminal with no image
+  protocol support; press `i` in the viewer to toggle them off. The pipeline
+  lives in `src/png.ts` (PNG decoder), `src/image-render.ts`
+  (image → cells), `src/image-loader.ts` (URL resolution + fetch cache),
+  `src/markdown-images.ts` (token helpers) and `src/markdown-view.ts` (the
+  renderable), and degrades to captions on runtimes without `Bun.Image`.
+
+### Changed
+
+- **The update modal's release notes render as markdown too.** The in-app
+  update panel reused the same text approximation as the README viewer; it
+  now shares `MarkdownRenderable` via the new view, so release notes show
+  real headings, lists, inline code, and boxed tables. Inline images stay
+  off there (the panel is narrow and notes are prose).
+- With both surfaces migrated, the plain-text markdown renderer
+  (`src/markdown-render.ts`) is no longer used and has been removed.
+
+---
+
 ## [9.7.1] — 2026-09-20 (released)
 
 ### Fixed

package/README.md

@@ -95,8 +95,21 @@ ghfind --compare a/b c/d     # side-by-side comparison
 ghfind --compare a/b c/d --json # comparison as JSON|CSV|Markdown
 ghfind deep-dive a/b --json  # deep-dive: languages, contributors, README
 ghfind pkg "query" --json    # npm package search as JSON
+# Read-only local state
+ghfind bookmarks             # saved repos, newest first
+ghfind history --limit 20    # past searches
+ghfind saved                 # named searches saved in the TUI
+ghfind topics                # popular GitHub topics
+ghfind readme a/b            # print a repo README (--raw for no header)
+ghfind share a/b --as gh-cli # share snippet (--copy also copies it)
+# Agent skills
+ghfind skill search testing      # skills installed on this machine
+ghfind skill search testing --remote --json  # the skills.sh ecosystem
 ```
 
+`bookmarks`, `history`, `saved`, `topics`, `readme` and `share` are read-only:
+they print what the TUI has stored but never modify local state.
+
 ## Use with AI agents
 
 ghfind speaks the [Model Context Protocol](https://modelcontextprotocol.io) —
@@ -120,17 +133,29 @@ or in your MCP client config:
 Exposed tools: `ghfind_search_repos`, `ghfind_trending`,
 `ghfind_npm_packages`, `ghfind_org_profile`, `ghfind_user_profile`,
 `ghfind_compare_repos`, `ghfind_deep_dive`, `ghfind_bookmarked_releases`,
-and `ghfind_skill` (a token-efficient CLI usage guide for agents).
+`ghfind_skill` (a token-efficient CLI usage guide for agents), and
+`ghfind_skill_search` (find agent skills, either installed on this machine or
+in the public skills.sh ecosystem ? read-only, it never installs anything).
 Unauthenticated requests are rate-limited to 60/hr — set `GITHUB_TOKEN`
 in the environment for 5,000/hr.
 
 CLI-first agents can skip MCP entirely:
 
 ```bash
-ghfind skill            # list agent skills
-ghfind skill ghfind-cli # print the token-efficient CLI guide
+ghfind skill                      # list agent skills
+ghfind skill ghfind-cli           # print the token-efficient CLI guide
+ghfind skill search testing       # search installed skills (local scan)
+ghfind skill search testing --remote --limit 10 --json  # search skills.sh
 ```
 
+`ghfind skill search` matches skill names first, then descriptions, and reads
+the `SKILL.md` files under `~/.codex/skills`, `~/.agents/skills`,
+`<project>/.codex/skills` and `<project>/.github/skills` (in that priority
+order, de-duplicated by name). `--remote` queries the public
+[skills.sh](https://skills.sh) ecosystem instead and returns the
+`npx skills add` command for each hit, without installing anything. Set
+`GHFIND_SKILL_ROOTS` to override which directories are scanned.
+
 ### Completions
 
 ```bash
@@ -164,6 +189,9 @@ ghfind --completion fish | source
 <tr><td><b>Watch</b></td><td><code>--watch</code> — poll for new results</td></tr>
 <tr><td><b>MCP server</b></td><td><code>ghfind mcp</code> — GitHub search as tools for AI agents (Claude Code, Cursor, …)</td></tr>
 <tr><td><b>Agent skill</b></td><td><code>ghfind skill</code> — token-efficient CLI usage guide for coding agents</td></tr>
+<tr><td><b>Skill search</b></td><td><code>ghfind skill search &lt;query&gt;</code> — find installed skills, or <code>--remote</code> for the skills.sh ecosystem (also <code>ghfind_skill_search</code> over MCP)</td></tr>
+<tr><td><b>Read-only state</b></td><td><code>ghfind bookmarks|history|saved|topics</code> — print local state and popular topics without modifying anything</td></tr>
+<tr><td><b>README &amp; share</b></td><td><code>ghfind readme a/b</code> and <code>ghfind share a/b --as gh-cli</code> — the TUI's <code>r</code> / <code>y</code> actions from the shell</td></tr>
 </table>
 
 <details>
@@ -207,7 +235,7 @@ Actions shown depend on current mode (search vs trending) and selection:
 | Refresh         | Re-run current search (or reload trending)              |
 | Toggle trending | Switch between search and trending views                |
 | Deep-dive       | Show languages, contributors, README excerpt            |
-| Readme          | Full README viewer                                      |
+| Readme          | Full markdown README viewer (inline images included)    |
 | Activity graph  | Toggle commit chart fullscreen                          |
 | Bookmark        | Save / unsave selected repo                             |
 | Compare         | Add/remove repo to comparison set                       |
@@ -233,6 +261,7 @@ Actions shown depend on current mode (search vs trending) and selection:
 | `d`                              | History / Bookmarks / Saved searches / Notifications | Delete current entry                        |
 | `Ctrl+X`                         | History                                              | Clear all history                           |
 | `Ctrl+C`                         | Notifications                                        | Dismiss all notifications                   |
+| `i`                              | README viewer                                        | Toggle inline images on/off                 |
 | `Y` / `N` / `L`                  | Update modal                                         | Yes (install) / No (skip) / Later (dismiss) |
 | `↑` / `↓` — `j` / `k`            | Update modal                                         | Scroll release notes                        |
 | `PgUp` / `PgDn` / `Home` / `End` | Update modal                                         | Jump through release notes                  |
@@ -271,7 +300,7 @@ Prefix with `-` to exclude. Supported: `language`, `stars`, `fork`, `archived`,
 }
 ```
 
-Env: `GITHUB_TOKEN`, `GHFIND_CONFIG`, `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_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/))
 
 ---
 
@@ -284,14 +313,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 355 tests
+bun test         # 414 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         # 355 tests
+npm test         # 414 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -300,10 +329,53 @@ 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
+[.issues/tickets/readme-image-rendering.md](.issues/tickets/readme-image-rendering.md)
+for the measurements and the remaining work.
+
+---
+
 ## Changelog
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
+### v9.8.1
+
+- **`ghfind skill search <query>`** finds agent skills by keyword and prints why
+  each one matched; `--remote` searches the public [skills.sh](https://skills.sh)
+  ecosystem instead, and `GHFIND_SKILL_ROOTS` overrides the scanned directories
+- **MCP tool `ghfind_skill_search`** — agents search installed skills or the
+  skills.sh registry as soon as they connect; read-only
+- **Read-only CLI views of local state** — `ghfind bookmarks`, `ghfind history`,
+  `ghfind saved`, `ghfind topics`, plus `ghfind readme <owner/repo>` and
+  `ghfind share <owner/repo>`, each with `--json` for agents
+- **Shell completions** (bash, zsh, fish) cover every new subcommand and flag
+- **README image rendering is incomplete** — see
+  [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
+
 ### 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
@@ -311,23 +383,6 @@ Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 - **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)
 
-### v9.7.0
-
-- **CLI parity with the MCP tools** — `ghfind deep-dive <owner/repo>` (languages, contributors, README excerpt, `--json`), `ghfind --compare` with `--json|--csv|--markdown`, and a trending language filter (`ghfind trending rust`, `--trending <lang>`)
-- **Deep-dive metadata fix** — real stars, description, and topics are fetched first instead of a zeroed stub; a 404 exits with `Repo not found`
-- Fixed `ghfind mcp` failing to typecheck (JSON-RPC id narrowing; runtime behavior unchanged)
-- The MCP server and CLI now share repo-ref parsing, language validation, and the deep-dive pipeline
-
-### v9.6.0
-
-- **MCP server (beta)** — `ghfind mcp` turns ghfind into a tool server: Claude Code, Cursor, Codex, and any MCP client can call GitHub search over stdio (nine tools, no new dependencies)
-- **Agent skill (beta)** — `ghfind skill` gives coding agents a token-efficient usage guide; `ghfind trending` accepts a language filter (`ghfind trending rust`)
-- **curl installer** — `curl -fsSL https://raw.githubusercontent.com/codersdfs/search-cli/main/scripts/install.sh | sh` downloads the standalone binary and verifies it against the release's `SHA256SUMS.txt`
-- **`NO_COLOR` support** — `ghfind --doctor` drops ANSI colors when `NO_COLOR` is set or stdout isn't a TTY
-- Fixed the stale `scripts/brew.rb` formula (wrong repo, version, and asset names)
-
----
-
 ## License
 
 MIT

package/completions/ghfind.bash

@@ -7,7 +7,7 @@ _ghfind() {
   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 pkg login init doctor org mcp skill trending deep-dive"
+  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)
@@ -30,6 +30,10 @@ _ghfind() {
       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

package/completions/ghfind.fish

@@ -20,5 +20,10 @@ 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 pkg mcp skill trending deep-dive"
+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

@@ -23,16 +23,29 @@ _ghfind() {
     '--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]:skill name:'
+    'skill[Print an agent skill guide, or search with: skill search <query>]:skill name:'
+    'compare[Compare repositories]'
   )
   _arguments "${opts[@]}" '*:query:'
 }