@wangjunjian/dsh-github-trending 0.1.0

package/lib/index.js

@@ -0,0 +1,147 @@
+/**
+ * `@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 z from '@deepseek-ai/schemastery';
+import { TrendingCache } from './cache.js';
+import { DEFAULT_REFRESH_INTERVAL_MS } from './constants.js';
+import { applyGithubTrendingTool, buildTrendingUrl, fetchTrendingRepositories, MAX_RESULTS_LIMIT } from './tool.js';
+export { DEFAULT_REFRESH_INTERVAL_MS } from './constants.js';
+export { DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT } from './tool.js';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'github-trending';
+/** Services this plugin requires. */
+export const inject = ['tools', 'systemPrompt', 'webServer'];
+/** Schemastery config schema with defaults and bounds. */
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+    timeoutMs: z.number().default(30_000),
+    maxResults: z.number().default(10),
+    refreshIntervalMs: z.number().default(DEFAULT_REFRESH_INTERVAL_MS),
+});
+/**
+ * Assert that a numeric config value is a positive finite integer.
+ *
+ * @param name - the config field name.
+ * @param value - the value to validate.
+ */
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`github-trending: ${name} must be a positive integer`);
+    }
+}
+/**
+ * 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 function apply(ctx, config) {
+    const resolved = config;
+    assertPositiveInteger('timeoutMs', resolved.timeoutMs);
+    assertPositiveInteger('maxResults', resolved.maxResults);
+    assertPositiveInteger('refreshIntervalMs', resolved.refreshIntervalMs);
+    if (!resolved.enabled)
+        return;
+    applyGithubTrendingTool(ctx, {
+        timeoutMs: resolved.timeoutMs,
+        maxResults: Math.min(resolved.maxResults, MAX_RESULTS_LIMIT),
+    });
+    const cache = new TrendingCache({
+        intervalMs: resolved.refreshIntervalMs,
+        timeoutMs: resolved.timeoutMs,
+    });
+    ctx.effect(() => () => {
+        cache.dispose();
+    }, 'github-trending: cache disposal');
+    // Pre-load daily/weekly/monthly so the browser UI can switch tabs instantly.
+    for (const since of ['daily', 'weekly', 'monthly']) {
+        const fetcher = async (signal) => {
+            const trendingUrl = buildTrendingUrl({ since });
+            return fetchTrendingRepositories(trendingUrl, signal);
+        };
+        cache.ensureScheduled(fetcher, undefined, since);
+        void cache.refresh(fetcher, undefined, since).catch(() => { });
+    }
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'prefix',
+        path: '/github-trending',
+        handler: createTrendingHandler(cache),
+    }), 'github-trending: web route');
+}
+/**
+ * Create the `/github-trending` HTTP handler that serves cached GitHub Trending
+ * data to the browser side. Runs from the host so it is not subject to browser
+ * CORS restrictions. Supports `?refresh=1` to force a host-side refetch.
+ *
+ * @param cache - shared trending cache.
+ * @returns the request handler.
+ */
+function createTrendingHandler(cache) {
+    return async (req, res) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed' }));
+            return;
+        }
+        const url = new URL(req.url ?? '/', 'http://x');
+        const language = url.searchParams.get('language') ?? undefined;
+        const sinceRaw = url.searchParams.get('since') ?? 'daily';
+        const since = sinceRaw === 'weekly' || sinceRaw === 'monthly' ? sinceRaw : 'daily';
+        const forceRefresh = url.searchParams.get('refresh') === '1';
+        try {
+            const fetchers = {
+                daily: async (signal) => {
+                    return fetchTrendingRepositories(buildTrendingUrl({ language, since: 'daily' }), signal);
+                },
+                weekly: async (signal) => {
+                    return fetchTrendingRepositories(buildTrendingUrl({ language, since: 'weekly' }), signal);
+                },
+                monthly: async (signal) => {
+                    return fetchTrendingRepositories(buildTrendingUrl({ language, since: 'monthly' }), signal);
+                },
+            };
+            for (const sinceValue of ['daily', 'weekly', 'monthly']) {
+                cache.ensureScheduled(fetchers[sinceValue], language, sinceValue);
+            }
+            let entry;
+            if (forceRefresh) {
+                const all = await cache.refreshAll(fetchers, language);
+                entry = all[since];
+            }
+            else if (cache.get(language, since) === undefined) {
+                entry = await cache.refresh(fetchers[since], language, since);
+            }
+            else {
+                entry = cache.get(language, since);
+            }
+            res.writeHead(200, {
+                'content-type': 'application/json; charset=utf-8',
+                'cache-control': 'no-cache',
+            });
+            res.end(JSON.stringify(entry));
+        }
+        catch (error) {
+            const cached = cache.get(language, since);
+            if (cached !== undefined) {
+                // Serve stale data when a background refresh fails.
+                res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    'cache-control': 'no-cache',
+                });
+                res.end(JSON.stringify(cached));
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            res.writeHead(502, { 'content-type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ error: message }));
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/parser.js

@@ -0,0 +1,121 @@
+/**
+ * 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
+ */
+import { parse as parseHtml } from 'node-html-parser';
+/**
+ * Parse a numeric string like "47,534" or "1.2k" into an integer.
+ *
+ * GitHub displays large counts with comma separators or compact suffixes.
+ * Unparseable values return `undefined` so the caller can default to `0`.
+ *
+ * @param text - raw numeric text from the page.
+ * @returns the parsed integer, or `undefined` when the text is not a count.
+ */
+function parseCount(text) {
+    if (text === undefined)
+        return undefined;
+    const normalized = text.trim().toLowerCase().replace(/,/g, '');
+    if (normalized === '')
+        return undefined;
+    const compact = /^(?<whole>\d+(?:\.\d+)?)(?<suffix>[km])$/.exec(normalized);
+    if (compact?.groups !== undefined) {
+        const value = Number.parseFloat(compact.groups.whole);
+        const multiplier = compact.groups.suffix === 'k' ? 1_000 : 1_000_000;
+        return Math.round(value * multiplier);
+    }
+    const numeric = Number(normalized);
+    return Number.isFinite(numeric) ? Math.round(numeric) : undefined;
+}
+/**
+ * Extract the owner and repository name from a heading link.
+ *
+ * The heading contains `<span class="text-normal">owner /</span> repo`, and the
+ * link `href` is `/owner/repo`. Prefer the `href` because it is unambiguous.
+ *
+ * @param link - the heading anchor element.
+ * @returns owner and name, or `undefined` when the link is malformed.
+ */
+function parseRepoName(link) {
+    const href = link.getAttribute('href');
+    if (href !== undefined) {
+        const parts = href.split('/').filter(Boolean);
+        if (parts.length >= 2) {
+            return { owner: parts[0], name: parts[1] };
+        }
+    }
+    const text = link.textContent ?? '';
+    const match = /^(?<owner>[^/\s]+)\s*\/\s*(?<name>[^/\s]+)$/.exec(text.trim());
+    if (match?.groups !== undefined) {
+        return { owner: match.groups.owner, name: match.groups.name };
+    }
+    return undefined;
+}
+/**
+ * Parse one `article.Box-row` into a {@link TrendingRepository}.
+ *
+ * @param article - the article element.
+ * @param rank - the 1-based position on the page.
+ * @returns the parsed repository, or `undefined` when the article has no
+ *   identifiable repository name.
+ */
+function parseArticle(article, rank) {
+    const link = article.querySelector('h2 a[href^="/"]');
+    if (link === null)
+        return undefined;
+    const repo = parseRepoName(link);
+    if (repo === undefined)
+        return undefined;
+    const description = article.querySelector('p')?.textContent?.trim() || undefined;
+    const language = article.querySelector('span[itemprop="programmingLanguage"]')?.textContent?.trim() || undefined;
+    const starsText = article.querySelector('a[href$="/stargazers"]')?.textContent;
+    const forksText = article.querySelector('a[href$="/forks"]')?.textContent;
+    let starsToday = 0;
+    const spans = article.querySelectorAll('span');
+    for (const span of spans) {
+        const text = span.textContent?.trim() ?? '';
+        // GitHub uses "X stars today" for daily, "X stars this week/month" for longer windows.
+        const match = /^(?<count>[\d,.]+[km]?)\s+stars?\s+(today|this week|this month)$/i.exec(text);
+        if (match?.groups !== undefined) {
+            starsToday = parseCount(match.groups.count) ?? 0;
+            break;
+        }
+    }
+    return {
+        rank,
+        owner: repo.owner,
+        name: repo.name,
+        fullName: `${repo.owner}/${repo.name}`,
+        url: `https://github.com/${repo.owner}/${repo.name}`,
+        description,
+        language,
+        stars: parseCount(starsText) ?? 0,
+        forks: parseCount(forksText) ?? 0,
+        starsToday,
+    };
+}
+/**
+ * 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 function parseTrendingHtml(html) {
+    const root = parseHtml(html);
+    const articles = root.querySelectorAll('article.Box-row');
+    const repositories = [];
+    for (let index = 0; index < articles.length; index += 1) {
+        const parsed = parseArticle(articles[index], index + 1);
+        if (parsed !== undefined) {
+            repositories.push(parsed);
+        }
+    }
+    return repositories;
+}
+//# sourceMappingURL=parser.js.map

package/lib/tool.js

@@ -0,0 +1,236 @@
+/**
+ * The model-facing `github_trending` tool.
+ *
+ * @module @wangjunjian/dsh-github-trending/tool
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { parseTrendingHtml } from './parser.js';
+/** Default cap on repositories returned by one tool call. */
+export const DEFAULT_MAX_RESULTS = 10;
+/** Hard upper bound on repositories returned by one tool call. */
+export const MAX_RESULTS_LIMIT = 25;
+/** User-Agent identifying this plugin's requests to GitHub. */
+export 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 function buildTrendingUrl(args) {
+    const base = 'https://github.com/trending';
+    const path = args.language !== undefined && args.language.trim() !== ''
+        ? `${base}/${encodeURIComponent(args.language.trim())}`
+        : base;
+    const since = args.since === 'weekly' || args.since === 'monthly' ? args.since : 'daily';
+    return `${path}?since=${since}`;
+}
+/**
+ * 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 function resolveMaxResults(requested, configCap) {
+    const cap = Math.min(configCap, MAX_RESULTS_LIMIT);
+    if (requested === undefined || !Number.isFinite(requested))
+        return Math.min(DEFAULT_MAX_RESULTS, cap);
+    return Math.max(1, Math.min(Math.round(requested), cap));
+}
+/**
+ * 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 async function fetchTrendingRepositories(url, signal) {
+    const response = await fetch(url, {
+        headers: {
+            'User-Agent': USER_AGENT,
+            Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+        },
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error(`GitHub Trending returned HTTP ${response.status}`);
+    }
+    const html = await response.text();
+    return parseTrendingHtml(html);
+}
+/**
+ * Format the canonical result as a concise markdown list for the model.
+ *
+ * @param result - the tool result value.
+ * @returns one text content block.
+ */
+export function formatTrendingOutput(result) {
+    if (result.repositories.length === 0) {
+        return 'No trending repositories found.';
+    }
+    const header = result.truncated
+        ? `Top ${result.repositories.length} trending repositories (truncated):`
+        : `Top ${result.repositories.length} trending repositories:`;
+    const lines = result.repositories.map((repo) => {
+        const today = repo.starsToday > 0 ? ` | +${repo.starsToday.toLocaleString()} today` : '';
+        const lang = repo.language !== undefined ? ` | ${repo.language}` : '';
+        const stars = repo.stars > 0 ? ` | ⭐ ${repo.stars.toLocaleString()}` : '';
+        const forks = repo.forks > 0 ? ` | 🍴 ${repo.forks.toLocaleString()}` : '';
+        const description = repo.description !== undefined ? `\n  ${repo.description}` : '';
+        return `${repo.rank}. [${repo.fullName}](${repo.url})${lang}${stars}${forks}${today}${description}`;
+    });
+    return [header, ...lines].join('\n');
+}
+/**
+ * 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 function presentTrendingCall(args) {
+    const language = args.language !== undefined && args.language.trim() !== '' ? args.language.trim() : 'all languages';
+    return {
+        card: 'generic',
+        title: `GitHub Trending: ${language} (${args.since})`,
+        kind: 'search',
+        rawInput: `${language} / ${args.since}`,
+    };
+}
+/**
+ * Build replayable presentation metadata for the completed call.
+ *
+ * @param result - the canonical tool result.
+ * @returns a compact JSON summary for UI cards.
+ */
+export function trendingMetaFromValue(result) {
+    return {
+        count: result.repositories.length,
+        truncated: result.truncated,
+        repositories: result.repositories.map((repo) => ({
+            fullName: repo.fullName,
+            url: repo.url,
+            starsToday: repo.starsToday,
+        })),
+    };
+}
+/**
+ * Narrow opaque replayed result metadata to the presentation shape.
+ *
+ * @param meta - result metadata.
+ * @returns the validated meta, or `undefined` for absent/malformed data.
+ */
+export function trendingMetaFromResult(meta) {
+    if (typeof meta !== 'object' || meta === null || Array.isArray(meta))
+        return undefined;
+    const { count, truncated, repositories } = meta;
+    if (typeof count !== 'number' || typeof truncated !== 'boolean' || !Array.isArray(repositories))
+        return undefined;
+    const repos = repositories.filter((repo) => {
+        if (typeof repo !== 'object' || repo === null)
+            return false;
+        const r = repo;
+        return typeof r.fullName === 'string' && typeof r.url === 'string' && typeof r.starsToday === 'number';
+    });
+    return { count, truncated, repositories: repos };
+}
+/**
+ * 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 function presentTrendingResult(args, result) {
+    if (result.isError)
+        return undefined;
+    const meta = trendingMetaFromResult(result.meta);
+    if (meta === undefined)
+        return undefined;
+    const language = args.language !== undefined && args.language.trim() !== '' ? args.language.trim() : 'all languages';
+    return {
+        card: 'search',
+        shape: 'paths',
+        title: `GitHub Trending: ${language} (${args.since})`,
+        paths: meta.repositories.map((repo) => repo.url),
+        total: meta.count,
+        truncated: meta.truncated,
+    };
+}
+/**
+ * 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 function applyGithubTrendingTool(ctx, config) {
+    ctx.systemPrompt.section({
+        name: 'tool:github_trending',
+        order: 112,
+        text: 'Use the github_trending tool to discover currently popular repositories on GitHub. It returns repository names, descriptions, languages, star counts, and stars gained today.',
+    });
+    ctx.tools.register(defineTool({
+        name: 'github_trending',
+        description: 'Fetch currently trending GitHub repositories for a language and time window.',
+        parameters: {
+            language: {
+                type: 'string',
+                description: 'Optional programming language filter (e.g. "python", "typescript", "go"). Omit to list trending repositories across all languages.',
+            },
+            since: {
+                type: 'string',
+                description: 'Time window: "daily", "weekly", or "monthly". Defaults to "daily".',
+            },
+            maxResults: {
+                type: 'integer',
+                description: `Maximum number of repositories to return (1-${Math.min(config.maxResults, MAX_RESULTS_LIMIT)}).`,
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    repositories: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                rank: { type: 'integer', required: true },
+                                owner: { type: 'string', required: true },
+                                name: { type: 'string', required: true },
+                                fullName: { type: 'string', required: true },
+                                url: { type: 'string', required: true },
+                                description: { type: 'string' },
+                                language: { type: 'string' },
+                                stars: { type: 'integer', required: true },
+                                forks: { type: 'integer', required: true },
+                                starsToday: { type: 'integer', required: true },
+                            },
+                        },
+                    },
+                    truncated: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: formatTrendingOutput(value) }],
+            presentationMeta: (_args, value) => trendingMetaFromValue(value),
+        },
+        timeoutMs: config.timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const language = typeof args.language === 'string' ? args.language : undefined;
+            const maxResults = resolveMaxResults(args.maxResults, config.maxResults);
+            const url = buildTrendingUrl({ language, since: args.since, maxResults });
+            const repositories = await fetchTrendingRepositories(url, exec.signal);
+            const truncated = repositories.length > maxResults;
+            const capped = repositories.slice(0, maxResults);
+            return { repositories: capped, truncated };
+        },
+        presentCall: presentTrendingCall,
+        presentResult: (args, result) => presentTrendingResult(args, result),
+    }));
+}
+//# sourceMappingURL=tool.js.map

package/lib/types/cache.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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
+ */
+import type { TrendingRepository } from './parser.js';
+export interface TrendingCacheEntry {
+    /** Cached repositories in page order. */
+    repositories: TrendingRepository[];
+    /** ISO timestamp of the cache write. */
+    cachedAt: string;
+}
+export interface TrendingCacheOptions {
+    /** Refresh interval in milliseconds for the periodic background refresh. */
+    intervalMs: number;
+    /** Request timeout in milliseconds. */
+    timeoutMs: number;
+}
+/**
+ * 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 declare class TrendingCache {
+    private readonly entries;
+    private readonly timers;
+    private readonly options;
+    constructor(options: TrendingCacheOptions);
+    /**
+     * 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: string | undefined, since: string): TrendingCacheEntry | undefined;
+    /**
+     * 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.
+     */
+    refresh(fetcher: (signal?: AbortSignal) => Promise<TrendingRepository[]>, language: string | undefined, since: string): Promise<TrendingCacheEntry>;
+    /**
+     * Fetch with a per-attempt timeout, retrying transient failures.
+     *
+     * @param fetcher - host-side fetcher that returns ranked repositories.
+     * @returns the fetched repositories.
+     */
+    private fetchWithRetry;
+    /**
+     * Store repositories under a key and return the wrapped entry.
+     *
+     * @param cachedAt - optional ISO timestamp; defaults to now.
+     */
+    set(language: string | undefined, since: string, repositories: TrendingRepository[], cachedAt?: string): TrendingCacheEntry;
+    /**
+     * 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.
+     */
+    refreshAll(fetchers: Record<string, (signal?: AbortSignal) => Promise<TrendingRepository[]>>, language: string | undefined): Promise<Record<string, TrendingCacheEntry>>;
+    /**
+     * 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: (signal?: AbortSignal) => Promise<TrendingRepository[]>, language: string | undefined, since: string): void;
+    /**
+     * Stop all background refresh timers. Call on plugin teardown.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/lib/types/client/GithubTrendingPanel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fixed right-hand overlay panel that displays cached GitHub Trending data.
+ *
+ * The panel is designed to feel like a layout column: it is docked to the right
+ * edge, has its own scrollbar, can be collapsed to a narrow rail, and its width
+ * is resizable. Because external plugins cannot declare new AppFrame grid
+ * columns in this version of DSH, the panel lives in `shell.overlay`. To avoid
+ * covering the conversation, it pushes the center/details columns via a runtime
+ * CSS variable set on the AppFrame root.
+ *
+ * @module @wangjunjian/dsh-github-trending/client/GithubTrendingPanel
+ */
+import type { GithubTrendingKey } from './locales.js';
+export interface GithubTrendingPanelProps {
+    /** Locale translator for the panel namespace. */
+    t: (key: GithubTrendingKey) => string;
+}
+/**
+ * Render the right-hand overlay panel.
+ * @param props - panel props.
+ */
+export declare function GithubTrendingPanel({ t }: GithubTrendingPanelProps): JSX.Element | null;
+//# sourceMappingURL=GithubTrendingPanel.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser half of the GitHub Trending plugin.
+ *
+ * Registers a `shell.overlay` entry that renders the right-hand trending panel.
+ * The panel is shown by default so no sidebar trigger is needed.
+ *
+ * @module @wangjunjian/dsh-github-trending/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type GithubTrendingKey } from './locales.js';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** GitHub Trending panel copy. */
+        'github-trending': GithubTrendingKey;
+    }
+}
+/** Required client services. */
+export declare const inject: string[];
+/**
+ * Register the GitHub Trending right-hand overlay panel.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Locale strings for the GitHub Trending sidebar action.
+ *
+ * @module @wangjunjian/dsh-github-trending/client/locales
+ */
+export type GithubTrendingKey = 'action.label' | 'action.close' | 'panel.title' | 'panel.daily' | 'panel.weekly' | 'panel.monthly' | 'panel.refresh' | 'panel.loading' | 'panel.empty' | 'panel.error' | 'panel.cachedAt' | 'panel.autoRefresh' | 'panel.collapse' | 'repo.stars' | 'repo.forks' | 'repo.today';
+export declare const en: Record<GithubTrendingKey, string>;
+export declare const zh: Record<GithubTrendingKey, string>;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Module-level store holding the overlay panel's UI state: open/closed,
+ * collapsed, selected time window, and width.
+ *
+ * @module @wangjunjian/dsh-github-trending/client/store
+ */
+export type Since = 'daily' | 'weekly' | 'monthly';
+export interface PanelState {
+    /** Whether the right-hand overlay panel is mounted at all. */
+    open: boolean;
+    /** Whether the panel is collapsed to a narrow rail. */
+    collapsed: boolean;
+    /** Selected time window. */
+    since: Since;
+    /** Panel width in pixels when expanded. */
+    width: number;
+}
+type Listener = () => void;
+declare class PanelStore {
+    private state;
+    private readonly listeners;
+    subscribe(listener: Listener): () => void;
+    getSnapshot(): PanelState;
+    private emit;
+    setOpen(open: boolean): void;
+    setCollapsed(collapsed: boolean): void;
+    toggleCollapsed(): void;
+    setSince(since: Since): void;
+    setWidth(width: number): void;
+}
+/** Singleton panel store used by the overlay panel. */
+export declare const panelStore: PanelStore;
+export {};
+//# sourceMappingURL=store.d.ts.map