@wangjunjian/dsh-github-trending 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangjunjian
+
+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

@@ -0,0 +1,106 @@
+# @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.

package/README.zh.md

@@ -0,0 +1,102 @@
+# @wangjunjian/dsh-github-trending
+
+中文 | [English](README.md)
+
+一个 DeepSeek Harness bundle 插件：暴露一个基于 https://github.com/trending
+的 `github_trending` 工具，并在 `web` profile 中提供一个右侧趋势面板。
+
+## 功能
+
+插件注册了一个面向模型的工具 `github_trending`：抓取公开的 GitHub
+Trending 页面（按语言和时间窗口），返回结构化的热门仓库列表。
+
+每条结果包含：
+
+- `rank` — 页面上的排名（从 1 开始）
+- `owner` / `name` / `fullName`
+- `url` — 仓库的完整 GitHub URL
+- `description` — 仓库简介
+- `language` — 主要编程语言
+- `stars` — 总 star 数
+- `forks` — fork 数
+- `starsToday` — 今天（或本周/本月）新增的 star 数
+
+在 `web` profile 下，插件还会在浏览器 UI 右侧渲染一个可停靠的趋势面板
+（daily/weekly/monthly 标签页、可拖拽调宽、可折叠为窄条），数据来自宿主侧
+内存缓存，通过 `/github-trending` HTTP 路由提供。
+
+## 安装
+
+将插件安装到某个 DeepSeek Harness profile，不会修改 `deepseek-harness`
+仓库本身：
+
+```sh
+# 从本地检出目录安装
+dsh plugin --profile headless add /Users/junjian/GitHub/wang-junjian/dsh-github-trending
+
+# 或从 npm registry 安装
+dsh plugin --profile headless add @wangjunjian/dsh-github-trending
+```
+
+使用 `--profile web` 可同时获得浏览器 UI 中的趋势面板。安装后 bundle 会
+自动追加到 `dsh.profile.bundles`。
+
+## 使用
+
+直接向 agent 提问即可：
+
+```text
+列出今天 trending 的 Python 仓库。
+```
+
+### 工具参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `language` | `string` | 否 | 语言过滤，如 `python`、`typescript`、`go`。 |
+| `since` | `string` | 否 | `daily`（默认）、`weekly` 或 `monthly`。 |
+| `maxResults` | `integer` | 否 | 返回的仓库数量上限（默认 10，硬上限 25）。 |
+
+### Cordis 配置
+
+bundle patch 默认插入一行配置。可在 profile 的 `cordis.patch.yml` 中覆盖：
+
+```yaml
+- id: github-trending
+  config:
+    enabled: true
+    timeoutMs: 30000
+    maxResults: 10
+    refreshIntervalMs: 14400000
+```
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `enabled` | `true` | 是否注册工具、缓存与 web 路由。 |
+| `timeoutMs` | `30000` | 每次 HTTP 请求的协作式超时预算（毫秒）。 |
+| `maxResults` | `10` | 工具返回仓库数上限（最大会被钳制到 25）。 |
+| `refreshIntervalMs` | `14400000` | UI 缓存的后台刷新间隔（毫秒，4 小时）。 |
+
+## 开发
+
+```sh
+pnpm install           # 安装依赖（pnpm 10；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` 是手工开发辅助脚本：用本地 Playwright 驱动
+浏览器访问 `http://127.0.0.1:3080` 截取 web 面板效果图；它不属于测试套件，
+需要本地安装 Playwright。
+
+## 已知限制
+
+- GitHub Trending 没有官方 API。解析器针对当前服务端渲染的 HTML 结构，
+  GitHub 改动页面标记时可能需要更新。
+- 未认证的请求受 GitHub IP 级速率限制约束。
+- 插件直接请求 GitHub，而不是通过 `ctx.web`，因此不继承 harness web
+  能力的抓取策略。
+- 面板通过 `shell.overlay` 浮于应用之上；DSH 目前尚无原生右侧栏插槽。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Patch layer for the @wangjunjian/dsh-github-trending bundle.
+# Inserts one row that registers the github_trending tool.
+
+- insert:
+    - id: github-trending
+      name: '@wangjunjian/dsh-github-trending'

package/lib/cache.js

@@ -0,0 +1,129 @@
+/**
+ * In-memory cache for GitHub Trending data, shared by the host-side web route
+ * and the periodic background refresh.
+ *
+ * @module @wangjunjian/dsh-github-trending/cache
+ */
+/** Cache key format: `${language}:${since}`. */
+function cacheKey(language, since) {
+    return `${language ?? ''}:${since}`;
+}
+/**
+ * Simple in-memory cache with periodic refresh.
+ *
+ * The cache is deliberately host-local: a browser reload re-fetches from this
+ * cache, but a host restart starts cold. This keeps the implementation small
+ * and avoids persisting third-party data.
+ */
+export class TrendingCache {
+    entries = new Map();
+    timers = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Read the current cache entry for a language/time window.
+     *
+     * @param language - optional language filter.
+     * @param since - time window.
+     * @returns the cached entry, or undefined when cold.
+     */
+    get(language, since) {
+        return this.entries.get(cacheKey(language, since));
+    }
+    /**
+     * Fetch fresh data and store it. Reuses the configured timeout.
+     *
+     * @param fetcher - host-side fetcher that returns ranked repositories.
+     * @param language - optional language filter.
+     * @param since - time window.
+     * @returns the freshly cached entry.
+     */
+    async refresh(fetcher, language, since) {
+        const repositories = await this.fetchWithRetry(fetcher);
+        return this.set(language, since, repositories);
+    }
+    /**
+     * Fetch with a per-attempt timeout, retrying transient failures.
+     *
+     * @param fetcher - host-side fetcher that returns ranked repositories.
+     * @returns the fetched repositories.
+     */
+    async fetchWithRetry(fetcher) {
+        const MAX_RETRIES = 3;
+        const RETRY_DELAY_MS = 500;
+        let lastError;
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => {
+                controller.abort();
+            }, this.options.timeoutMs);
+            try {
+                return await fetcher(controller.signal);
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < MAX_RETRIES) {
+                    await new Promise((resolve) => {
+                        setTimeout(resolve, RETRY_DELAY_MS);
+                    });
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Store repositories under a key and return the wrapped entry.
+     *
+     * @param cachedAt - optional ISO timestamp; defaults to now.
+     */
+    set(language, since, repositories, cachedAt) {
+        const entry = { repositories, cachedAt: cachedAt ?? new Date().toISOString() };
+        this.entries.set(cacheKey(language, since), entry);
+        return entry;
+    }
+    /**
+     * Fetch fresh data for all time windows and store them with a single timestamp.
+     *
+     * @param fetchers - fetcher for each time window.
+     * @param language - optional language filter.
+     * @returns the freshly cached entries for all windows.
+     */
+    async refreshAll(fetchers, language) {
+        const cachedAt = new Date().toISOString();
+        const results = {};
+        for (const [since, fetcher] of Object.entries(fetchers)) {
+            const repositories = await this.fetchWithRetry(fetcher);
+            results[since] = this.set(language, since, repositories, cachedAt);
+        }
+        return results;
+    }
+    /**
+     * Ensure a periodic refresh is running for the given key. Idempotent.
+     *
+     * @param fetcher - host-side fetcher.
+     * @param language - optional language filter.
+     * @param since - time window.
+     */
+    ensureScheduled(fetcher, language, since) {
+        const key = cacheKey(language, since);
+        if (this.timers.has(key))
+            return;
+        this.timers.set(key, setInterval(() => {
+            void this.refresh(fetcher, language, since).catch(() => { });
+        }, this.options.intervalMs));
+    }
+    /**
+     * Stop all background refresh timers. Call on plugin teardown.
+     */
+    dispose() {
+        for (const timer of this.timers.values())
+            clearInterval(timer);
+        this.timers.clear();
+    }
+}
+//# sourceMappingURL=cache.js.map