@wangjunjian/dsh-github-trending

Readme

# @wangjunjian/dsh-github-trending

[中文](README.zh.md) | English

A DeepSeek Harness bundle plugin that exposes a `github_trending` tool backed by
https://github.com/trending, plus a right-hand trending panel in the `web`
profile.

## What it does

The plugin registers one model-facing tool, `github_trending`, that fetches the
public GitHub Trending page for a given language and time window and returns a
structured list of trending repositories.

Each result includes:

- `rank` — 1-based position on the page
- `owner` / `name` / `fullName`
- `url` — absolute GitHub repository URL
- `description` — repository tagline
- `language` — primary language
- `stars` — total star count
- `forks` — fork count
- `starsToday` — stars gained today (or this week/month)

In the `web` profile, the plugin additionally renders a dockable right-hand
panel (daily/weekly/monthly tabs, resizable, collapsible to a rail) backed by a
host-side in-memory cache served over the `/github-trending` HTTP route.

## Installation

Install the plugin into a DeepSeek Harness profile. The plugin does not modify
the `deepseek-harness` repository itself.

```sh
# From a local checkout
dsh plugin --profile headless add /Users/junjian/GitHub/wang-junjian/dsh-github-trending

# Or from the npm registry
dsh plugin --profile headless add @wangjunjian/dsh-github-trending
```

Use `--profile web` to also get the trending panel in the browser UI. The
bundle is appended to `dsh.profile.bundles` automatically.

## Usage

Ask the agent to list trending repositories:

```text
Show me today's trending Python repositories.
```

### Tool parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `language` | `string` | no | Programming language filter, e.g. `python`, `typescript`, `go`. |
| `since` | `string` | no | `daily` (default), `weekly`, or `monthly`. |
| `maxResults` | `integer` | no | Maximum repositories to return (default 10, hard cap 25). |

### Cordis config

The bundle patch inserts one row by default. You can override its config in your
profile's `cordis.patch.yml`:

```yaml
- id: github-trending
  config:
    enabled: true
    timeoutMs: 30000
    maxResults: 10
    refreshIntervalMs: 14400000
```

| Field | Default | Description |
|---|---|---|
| `enabled` | `true` | Whether to register the tool, cache, and web route. |
| `timeoutMs` | `30000` | Cooperative timeout budget (ms) for each HTTP request. |
| `maxResults` | `10` | Maximum repositories the tool may return (clamped to 25). |
| `refreshIntervalMs` | `14400000` | Background refresh interval (ms) for the UI cache (4 hours). |

## Development

```sh
pnpm install           # install dependencies (pnpm 10; also builds via prepare)
pnpm run build         # tsc -b tsconfig.json && tsdown
pnpm run test          # vitest run
pnpm run typecheck     # tsc --noEmit
pnpm run lint          # biome check .
pnpm run lint:fix      # biome check --write .
```

`scripts/screenshot_test.py` is a manual development aid that drives a local
Playwright browser against `http://127.0.0.1:3080` to screenshot the web panel;
it is not part of the test suite and requires a local Playwright install.

## Known limitations

- GitHub Trending has no official API. The parser targets the current
  server-rendered HTML layout and may need updates if GitHub changes markup.
- Unauthenticated requests are subject to GitHub's IP rate limits.
- The plugin fetches GitHub directly rather than through `ctx.web`, so it does
  not inherit the harness web capability's fetch policies.
- The panel floats over the app via `shell.overlay`; no native right-column
  slot exists in DSH yet.