@wangjunjian/dsh-github-trending 0.1.0

package/lib/types/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Constants shared by the host half and the browser half of the plugin.
+ *
+ * The client bundle inlines this module (it is a local value import, not a
+ * `@deepseek-ai/*` import), so both halves always agree on these values.
+ *
+ * @module @wangjunjian/dsh-github-trending/constants
+ */
+/** Default background refresh interval: 4 hours. Also the panel polling interval. */
+export declare const DEFAULT_REFRESH_INTERVAL_MS: number;
+//# sourceMappingURL=constants.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@wangjunjian/dsh-github-trending`: a DeepSeek Harness bundle plugin that
+ * registers a `github_trending` tool backed by https://github.com/trending.
+ *
+ * The plugin is a Cordis function/namespace plugin (no default export). It
+ * injects `tools` and `systemPrompt` and registers the tool through the
+ * harness tool registry.
+ *
+ * @module @wangjunjian/dsh-github-trending
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { DEFAULT_REFRESH_INTERVAL_MS } from './constants.js';
+export type { TrendingRepository } from './parser.js';
+export type { GithubTrendingArgs, GithubTrendingResult } from './tool.js';
+export { DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT } from './tool.js';
+/** Plugin config accepted from cordis.yml. */
+export interface Config {
+    /** Whether to register the `github_trending` tool. Defaults to true. */
+    enabled?: boolean;
+    /** Cooperative timeout budget (ms) for the HTTP request. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Maximum repositories the tool may return. Defaults to 10, hard cap 25. */
+    maxResults?: number;
+    /** Background refresh interval (ms) for the UI cache. Defaults to 14400000 (4 hours). */
+    refreshIntervalMs?: number;
+}
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "github-trending";
+/** Services this plugin requires. */
+export declare const inject: string[];
+/** Schemastery config schema with defaults and bounds. */
+export declare const Config: z<Config>;
+/**
+ * Register the `github_trending` tool and its system-prompt guidance.
+ *
+ * @param ctx - the Cordis context.
+ * @param config - plugin config; schemastery has already applied defaults.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/parser.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HTML parser for the public GitHub Trending page (https://github.com/trending).
+ *
+ * GitHub Trending has no official API, so this module scrapes the server-rendered
+ * HTML. The selectors target the current `article.Box-row` layout and degrade
+ * gracefully when GitHub changes markup: missing fields become `undefined` or `0`
+ * rather than throwing.
+ *
+ * @module @wangjunjian/dsh-github-trending/parser
+ */
+/** One trending repository extracted from the GitHub Trending page. */
+export interface TrendingRepository {
+    /** 1-based position on the page. */
+    rank: number;
+    /** Repository owner login. */
+    owner: string;
+    /** Repository name. */
+    name: string;
+    /** `owner/name`. */
+    fullName: string;
+    /** Absolute GitHub URL. */
+    url: string;
+    /** Repository description, if present. */
+    description?: string;
+    /** Primary language, if present. */
+    language?: string;
+    /** Total star count, if present. */
+    stars: number;
+    /** Fork count, if present. */
+    forks: number;
+    /** Stars gained today (or this week/month), if present. */
+    starsToday: number;
+}
+/**
+ * Parse the GitHub Trending HTML and return the extracted repositories.
+ *
+ * @param html - the raw HTML body from https://github.com/trending.
+ * @returns the list of trending repositories in page order.
+ */
+export declare function parseTrendingHtml(html: string): TrendingRepository[];
+//# sourceMappingURL=parser.d.ts.map

package/lib/types/tool.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The model-facing `github_trending` tool.
+ *
+ * @module @wangjunjian/dsh-github-trending/tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { GenericCallView, JsonValue, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools';
+import { type TrendingRepository } from './parser.js';
+/** Default cap on repositories returned by one tool call. */
+export declare const DEFAULT_MAX_RESULTS = 10;
+/** Hard upper bound on repositories returned by one tool call. */
+export declare const MAX_RESULTS_LIMIT = 25;
+/** Tool schema arguments after validation. */
+export interface GithubTrendingArgs {
+    /** Optional programming language filter (e.g. "python", "typescript"). */
+    language?: string;
+    /** Time window for trending computation: "daily", "weekly", or "monthly". Defaults to "daily". */
+    since?: string;
+    /** Maximum number of repositories to return. */
+    maxResults?: number;
+}
+/** Canonical tool result value. */
+export interface GithubTrendingResult {
+    /** Trending repositories in page order. */
+    repositories: TrendingRepository[];
+    /** True when the result was capped to `maxResults`. */
+    truncated: boolean;
+}
+/** User-Agent identifying this plugin's requests to GitHub. */
+export declare const USER_AGENT = "@wangjunjian/dsh-github-trending/0.1.0 (+https://github.com/wang-junjian/dsh-github-trending)";
+/**
+ * Resolve the GitHub Trending URL from tool arguments.
+ *
+ * @param args - validated tool arguments.
+ * @returns the HTTPS URL to fetch.
+ */
+export declare function buildTrendingUrl(args: GithubTrendingArgs): string;
+/**
+ * Validate and clamp `maxResults` to the configured cap.
+ *
+ * @param requested - the model-requested limit.
+ * @param configCap - the plugin-level cap from config.
+ * @returns a positive integer not exceeding the cap.
+ */
+export declare function resolveMaxResults(requested: number | undefined, configCap: number): number;
+/**
+ * Fetch the GitHub Trending page and parse it into repositories.
+ *
+ * @param url - the trending URL to fetch.
+ * @param signal - cancellation signal forwarded from the tool execution.
+ * @returns the parsed repositories.
+ */
+export declare function fetchTrendingRepositories(url: string, signal?: AbortSignal): Promise<TrendingRepository[]>;
+/**
+ * Format the canonical result as a concise markdown list for the model.
+ *
+ * @param result - the tool result value.
+ * @returns one text content block.
+ */
+export declare function formatTrendingOutput(result: GithubTrendingResult): string;
+/**
+ * Pending-call presentation: a search-style generic card titled by the language
+ * and time window.
+ *
+ * @param args - the raw tool arguments.
+ * @returns the generic pending card.
+ */
+export declare function presentTrendingCall(args: GithubTrendingArgs): GenericCallView;
+/** Replayable presentation metadata for one repository. */
+interface TrendingRepoMeta {
+    fullName: string;
+    url: string;
+    starsToday: number;
+}
+/** Replayable presentation metadata for the completed call. */
+interface TrendingMeta {
+    count: number;
+    truncated: boolean;
+    repositories: TrendingRepoMeta[];
+}
+/**
+ * Build replayable presentation metadata for the completed call.
+ *
+ * @param result - the canonical tool result.
+ * @returns a compact JSON summary for UI cards.
+ */
+export declare function trendingMetaFromValue(result: GithubTrendingResult): JsonValue;
+/**
+ * Narrow opaque replayed result metadata to the presentation shape.
+ *
+ * @param meta - result metadata.
+ * @returns the validated meta, or `undefined` for absent/malformed data.
+ */
+export declare function trendingMetaFromResult(meta: unknown): TrendingMeta | undefined;
+/**
+ * Completed-call presentation: a search result card with the repository list.
+ *
+ * @param args - the raw tool arguments.
+ * @param result - the final tool result.
+ * @returns the search result view, or `undefined` on error/malformed meta.
+ */
+export declare function presentTrendingResult(args: GithubTrendingArgs, result: ToolResult): SearchResultView | undefined;
+/** Plugin-level config received by {@link applyGithubTrendingTool}. */
+export interface ToolConfig {
+    /** Cooperative timeout budget (ms) for the HTTP request. */
+    timeoutMs: number;
+    /** Maximum repositories the tool may return. */
+    maxResults: number;
+}
+/**
+ * Register the `github_trending` tool and its system-prompt guidance.
+ *
+ * @param ctx - the Cordis context whose `tools` and `systemPrompt` registries receive the registrations.
+ * @param config - resolved plugin config: timeout and result cap.
+ */
+export declare function applyGithubTrendingTool(ctx: Context, config: ToolConfig): void;
+export {};
+//# sourceMappingURL=tool.d.ts.map

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@wangjunjian/dsh-github-trending",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness bundle plugin that exposes a github_trending tool backed by https://github.com/trending",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wang-junjian/dsh-github-trending.git"
+  },
+  "homepage": "https://github.com/wang-junjian/dsh-github-trending#readme",
+  "bugs": {
+    "url": "https://github.com/wang-junjian/dsh-github-trending/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "github",
+    "trending"
+  ],
+  "type": "module",
+  "packageManager": "pnpm@10.33.2",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/tool.js",
+    "lib/parser.js",
+    "lib/cache.js",
+    "lib/constants.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "external": [
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json && tsdown",
+    "prepare": "tsc -b tsconfig.json && tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "node-html-parser": "^7.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}