dsh-plugin-explorer

A local tool for the DeepSeek Harness web GUI that browses the GitHub
dsh-plugin topic: every repo's
name, README, and statistics (stars, forks, open issues, language,
license, last update, topics), with a Sync button to refresh the data, an
in-memory search, top-tag filtering, and sorting (stars / last
update / created, ascending or descending).

It is a client plugin
(dsh.client dual-face package) that mounts one entry into the sidebar's
footer action list (sidebar.footer.action): a Plugin Explorer trigger
beside Settings that opens the tool's modal.

Using the tool

1. Open the web GUI (http://127.0.0.1:3080) and refresh the page.
2. Click Plugin Explorer in the sidebar footer (bottom-left, next to Settings).
3. Press Sync to fetch the topic's repos from the GitHub search API
   (sorted by stars). Keywords in the search box and the selected tag
   are folded into the GitHub query (e.g. topic:dsh-plugin agent topic:python),
   so a scoped sync fetches exactly that matching subset instead of GitHub's
   1000-result cap truncating the whole topic, and the fetched subset replaces
   the cached snapshot. The status line shows the GitHub query of the last
   sync.
4. Search filters the cached snapshot by repo name, description, topics,
   language, license, and README text (readmes the tool already fetched).
5. Top tags below the search box lists the ten most common topic tags by
   repo count (generic tags — dsh, dsh-plugin, dsh-plugins,
   deepseek, deepseek-harness, ai-agent, ai-agents — are
   excluded); click one to filter to repos carrying that tag (click again or
   use Clear tag to remove the filter). The tag filter combines with
   search.
6. Sort (next to search): three field buttons — Stars, Last update,
   Created (the active one is highlighted) — plus an explicit Asc/Desc
   toggle (default: stars, descending). Created needs creation dates, which a
   fresh sync fills in (the status line says so when the cached snapshot
   predates them).
7. Expand a repo's README to load and render it (fetched lazily on first
   expand, then cached).
8. Install / Uninstall (next to the README toggle): the button shows
   Install once a repo's README is known to carry an install command
   (dsh plugin add <pkg>, pnpm add <pkg>, npm install <pkg>, or
   yarn add <pkg> — only the package name is detected, never a command
   line). If no install instruction can be found in the README (or the repo
   has no README at all), the button is disabled and reads Cannot install
   directly in grey. The README is fetched lazily, so for repos never
   expanded the button starts as plain Install; clicking it probes the
   README first and flips to the disabled grey state when it turns out to
   carry no install command. Once a repo's package is installed in the
   profile, the button switches to a danger-tinted Uninstall that removes
   it again (dsh plugin --profile web remove <package>). The installed
   state is authoritative — the host reads the profile's actual dependencies
   and the list refreshes on modal open and after every successful
   install/uninstall (a failed install never flips the button). Both actions
   require an acknowledgement prompt; only the package name crosses the wire
   — never a command line — and the host validates it against npm naming
   rules before spawning the CLI. If pnpm 10+/11 blocks dependency build
   scripts (ERR_PNPM_IGNORED_BUILDS), the host flips the exact packages
   pnpm listed to true in the profile's pnpm-workspace.yaml
allowBuilds map and retries the install once.

Data persists in localStorage under dsh-plugin-explorer:repos:v1 and
dsh-plugin-explorer:readmes:v1, so the list survives restarts and works
offline. The readme cache is size-bounded (oldest entries evicted).

Status line

The line under the toolbar summarizes the current view: repo counts, when the
snapshot was synced, the topic total, the active tag, the GitHub query of the
last sync, a hint when creation dates are missing, the active sort
(· sorted: Stars ↓), and a build tag (e.g. · b13) identifying the exact
bundle the browser runs. If the build tag is missing or older than the
latest, the browser is on a stale bundle — refresh the page.

GitHub API notes

• Unauthenticated REST rate limits apply (60 req/h core, 10 req/min search,
  per IP). One full sync costs up to 10 search requests; READMEs cost one
  request each and are cached. Rate-limit hits abort gracefully with a
  message and keep the previous data (a partial sync is preserved).
• The tool talks to api.github.com straight from the browser (CORS is
  permissive); no token is required for public data. If you hit limits often,
  set a GITHUB_TOKEN? No — the browser cannot read your env; the tool is
  intentionally anonymous.

Architecture

src/
  index.ts              node half: default-exported PluginInstallerGateway
                        (a Typert Remote service; source-mode dispatch)
  installer.ts          host: install/uninstall/installed remotes that drive
                        the dsh CLI, plus pnpm build-script approval (js-yaml)
  types.ts              wire types (InstallRequest/InstallResult) shared by
                        both halves
  client/
    index.ts            browser half: inject ['slots', 'remote', 'typert'],
                        mounts the installer Remote lazily, registers
                        RepoExplorer into 'sidebar.footer.action'
    RepoExplorer.tsx    trigger + modal: sync, search, tags, sort, README
                        expand, install/uninstall prompts
    RepoExplorer.module.css
    install-remote.ts   hand-written Typert Remote descriptors + type merges
    install-guide.ts    README install-command detection
    github.ts           GitHub REST client + localStorage cache + helpers

The browser bundle (lib/client.js) is emitted by tsdown in the shell's
closure-factory format: window.__ModuleLoader__.load({ id, factory }) with
the frozen platform module table as externals (react, @deepseek-ai/cordis,
@deepseek-ai/dsh-client-ui-primitives, ...), CSS Modules compiled by
lightningcss and injected as <style data-plugin> tags.

Installer Remote

The installer is a Typert Remote gateway (pluginInstaller): the browser
mounts hand-written descriptors (add, uninstall, installed) and the api
gateway dispatches to the host service through its @Remote markers. The
wire contract mirrors the host method signatures exactly — one request
parameter per action — and the install endpoint is named add because the
client namespace service reserves install and remove for its own members
(mounting a colliding name throws). Only a validated npm package name crosses
the wire; the CLI is spawned with an argument array, never a shell.

Mounting into the GUI

The tool is mounted through the web profile's user patch layer (no changes
to the DeepSeek Harness checkout):

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: dsh-plugin-explorer
      name: dsh-plugin-explorer

plus a symlink so the profile can resolve the package:

ln -s /Users/boxiao/Documents/dev/dhs-plugin-explorer \
      /Users/boxiao/.dsh/profiles/node_modules/dsh-plugin-explorer

New rows are read at GUI boot (config hot-reload is off in the web profile),
so a restart of the dsh web process was required once. After that,
rebuilds of lib/client.js hot-reload through the client-plugin HMR chain
(the host polls the bundle and broadcasts rebuilt over SSE; no refresh
needed). Host-half changes (the installer gateway) load only at boot, so they
require a GUI restart.

Development loop

pnpm install          # registry dev deps only; dsh types resolve through a
                      # node_modules/@deepseek-ai -> ~/.dsh/profiles/node_modules/@deepseek-ai
                      # symlink (the exact package versions the GUI runs)
pnpm run typecheck    # tsc --noEmit against the real dsh .d.ts artifacts
pnpm run build        # tsc -p tsconfig.host.json (host half: decorators are
                      # lowered to plain JS) then tsdown: lib/index.js +
                      # lib/client.js (+ .map)
pnpm run watch        # tsdown --watch (browser half only); bundle rewrites
                      # trigger client HMR. Host-half source edits need a
                      # `tsc -p tsconfig.host.json` run first, then a GUI restart.

Known limitations

• GitHub search caps topic results at 1000 of ~2370 repos; the status line
  reports the topic total and the capped list length.
• The list renders the first 300 matches at once (scroll container); the
  status line notes when more matches exist.
• Unauthenticated rate limits can interrupt a sync; partial results are kept
  and the UI explains the reset time.
• Install/uninstall edits the profile's dependencies; the change mounts or
  unmounts only after a GUI restart (the result message says so).