@czj-git/dsh-plugin-hub 0.1.0

package/dist/api.js

@@ -0,0 +1,243 @@
+import { z } from 'zod';
+/** Locales supported by the public DSH Plugin Hub API. */
+export const pluginHubLocales = ['zh', 'en'];
+/** Public plugin categories exposed by DSH Plugin Hub. */
+export const pluginHubCategories = [
+    'agent-workflow',
+    'coding-tools',
+    'models-data',
+    'ui-experience',
+    'integrations',
+    'security-governance',
+    'multimodal-creative',
+    'observability-cost',
+    'other',
+];
+/** Plugin runtime shapes supported by the public API. */
+export const pluginHubTypes = ['host', 'client', 'hybrid'];
+/** Install sources supported by the public API. */
+export const pluginHubSources = ['npm', 'github'];
+/** Ordering modes supported by the public API. */
+export const pluginHubSorts = ['relevance', 'growth', 'stars', 'newest', 'active'];
+const nullableInteger = z.number().int().nullable();
+const pluginSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    owner: z.string(),
+    repo: z.string(),
+    description: z.string(),
+    type: z.enum(pluginHubTypes),
+    category: z.enum(pluginHubCategories),
+    topics: z.array(z.string()),
+    language: z.string(),
+    license: z.string(),
+    package: z.object({
+        name: z.string(),
+        version: z.string(),
+        source: z.enum(pluginHubSources),
+        sourceSpec: z.string(),
+        installCommand: z.string(),
+        profile: z.string(),
+    }),
+    compatibility: z.object({
+        harnessVersion: z.string(),
+        verificationLevel: z.enum(['static-checked', 'runtime-verified']),
+        smokeStatus: z.enum(['static-passed', 'passed', 'manual-step-required', 'failed', 'not-run']),
+        validatedAt: z.string(),
+    }),
+    metrics: z.object({
+        stars: z.number().int(),
+        starsDelta1d: nullableInteger,
+        forks: z.number().int(),
+        openIssues: z.number().int(),
+        views: z.number().int(),
+    }),
+    timestamps: z.object({
+        listedAt: z.string(),
+        lastPushedAt: z.string(),
+        sourceUpdatedAt: z.string(),
+    }),
+    links: z.object({
+        detail: z.url(),
+        repository: z.url(),
+    }),
+});
+const responseSchema = z.object({
+    items: z.array(pluginSchema),
+    pagination: z.object({
+        page: z.number().int(),
+        perPage: z.number().int(),
+        total: z.number().int(),
+        totalPages: z.number().int(),
+    }),
+    meta: z.object({
+        apiVersion: z.literal('v1'),
+        locale: z.enum(pluginHubLocales),
+        query: z.string(),
+        sort: z.enum(pluginHubSorts),
+        dataUpdatedAt: z.string(),
+    }),
+});
+const errorSchema = z.object({
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        fields: z.record(z.string(), z.string()).optional(),
+    }),
+});
+/** An HTTP or response-validation failure returned by DSH Plugin Hub. */
+export class PluginHubApiError extends Error {
+    code;
+    status;
+    fields;
+    retryAfterSeconds;
+    /**
+     * Create one stable public-API failure.
+     * @param message - Human-readable failure.
+     * @param options - Structured HTTP and API diagnostics.
+     */
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'PluginHubApiError';
+        this.code = options.code;
+        this.status = options.status ?? null;
+        this.fields = Object.freeze({ ...(options.fields ?? {}) });
+        this.retryAfterSeconds = options.retryAfterSeconds ?? null;
+    }
+}
+/**
+ * Validate and canonicalize the configured service origin.
+ * @param raw - User-configured base URL.
+ * @returns An HTTP(S) origin without a trailing slash.
+ */
+export function normalizePluginHubBaseUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error('baseUrl must use http or https');
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error('baseUrl must not contain credentials, a query, or a fragment');
+    }
+    url.pathname = url.pathname.replace(/\/+$/, '');
+    return url.toString().replace(/\/$/, '');
+}
+function positiveInteger(name, value, maximum) {
+    if (!Number.isInteger(value) || value < 1 || value > maximum) {
+        throw new Error(`${name} must be an integer from 1 to ${maximum}`);
+    }
+    return value;
+}
+function optionalHeaderInteger(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || raw.trim() === '')
+        return null;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function rateLimitFrom(headers) {
+    return {
+        limit: optionalHeaderInteger(headers, 'RateLimit-Limit'),
+        remaining: optionalHeaderInteger(headers, 'RateLimit-Remaining'),
+        reset: headers.get('RateLimit-Reset'),
+        retryAfterSeconds: optionalHeaderInteger(headers, 'Retry-After'),
+    };
+}
+function normalizeQuery(query) {
+    const normalized = query?.trim().replace(/\s+/g, ' ') ?? '';
+    if (normalized.length > 100)
+        throw new Error('query must contain at most 100 characters');
+    return normalized;
+}
+/** Read-only client for the versioned DSH Plugin Hub search endpoint. */
+export class PluginHubClient {
+    #baseUrl;
+    #timeoutMs;
+    #fetch;
+    /**
+     * Create a client with one deployment's network policy.
+     * @param options - Service origin, request timeout, and optional test transport.
+     */
+    constructor(options) {
+        this.#baseUrl = normalizePluginHubBaseUrl(options.baseUrl);
+        this.#timeoutMs = positiveInteger('timeoutMs', options.timeoutMs, 120_000);
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    /**
+     * Search published, verified plugins.
+     * @param input - Public search filters and page controls.
+     * @param signal - Caller-owned cancellation signal.
+     * @returns Validated API data plus anonymous quota headers.
+     */
+    async search(input, signal) {
+        const url = new URL('/api/v1/plugins/search', this.#baseUrl);
+        const query = normalizeQuery(input.query);
+        if (query)
+            url.searchParams.set('q', query);
+        if (input.locale)
+            url.searchParams.set('locale', input.locale);
+        if (input.category)
+            url.searchParams.set('category', input.category);
+        if (input.type)
+            url.searchParams.set('type', input.type);
+        if (input.source)
+            url.searchParams.set('source', input.source);
+        if (input.sort)
+            url.searchParams.set('sort', input.sort);
+        url.searchParams.set('page', String(positiveInteger('page', input.page ?? 1, 1000)));
+        url.searchParams.set('per_page', String(positiveInteger('perPage', input.perPage ?? 10, 50)));
+        const timeout = AbortSignal.timeout(this.#timeoutMs);
+        const requestSignal = AbortSignal.any([signal, timeout]);
+        let response;
+        try {
+            response = await this.#fetch(url, {
+                method: 'GET',
+                headers: { Accept: 'application/json' },
+                signal: requestSignal,
+            });
+        }
+        catch (error) {
+            const message = signal.aborted
+                ? 'DSH Plugin Hub request was cancelled.'
+                : timeout.aborted
+                    ? `DSH Plugin Hub request timed out after ${this.#timeoutMs} ms.`
+                    : 'Could not reach DSH Plugin Hub.';
+            throw new PluginHubApiError(message, { code: signal.aborted ? 'CANCELLED' : timeout.aborted ? 'TIMEOUT' : 'NETWORK_ERROR', cause: error });
+        }
+        const rateLimit = rateLimitFrom(response.headers);
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch (error) {
+            throw new PluginHubApiError('DSH Plugin Hub returned non-JSON data.', {
+                code: 'INVALID_RESPONSE',
+                status: response.status,
+                cause: error,
+            });
+        }
+        if (!response.ok) {
+            const parsed = errorSchema.safeParse(payload);
+            const code = parsed.success ? parsed.data.error.code : `HTTP_${response.status}`;
+            const detail = parsed.success ? parsed.data.error.message : `HTTP ${response.status}`;
+            throw new PluginHubApiError(`DSH Plugin Hub request failed: ${detail}`, {
+                code,
+                status: response.status,
+                ...(parsed.success && parsed.data.error.fields
+                    ? { fields: parsed.data.error.fields }
+                    : {}),
+                retryAfterSeconds: rateLimit.retryAfterSeconds,
+            });
+        }
+        const parsed = responseSchema.safeParse(payload);
+        if (!parsed.success) {
+            throw new PluginHubApiError('DSH Plugin Hub returned an unsupported response.', {
+                code: 'INVALID_RESPONSE',
+                status: response.status,
+                cause: parsed.error,
+            });
+        }
+        return { ...parsed.data, rateLimit };
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Model-facing DSH Plugin Hub search and ranking tools.
+ * @module dsh-plugin-hub
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { type PluginHubLocale } from './api.js';
+export declare const name = "dsh-plugin-hub";
+export declare const inject: string[];
+/** Deployment settings for the public Plugin Hub client. */
+export interface Config {
+    baseUrl: string;
+    locale: PluginHubLocale;
+    timeoutMs: number;
+    maxResults: number;
+}
+/** Validated plugin configuration. */
+export declare const Config: Schema<Config>;
+/**
+ * Register the read-only search and ranking tools.
+ * @param ctx - Cordis context carrying the Harness tool registry.
+ * @param config - Validated service and result bounds.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export * from './api.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,107 @@
+/**
+ * Model-facing DSH Plugin Hub search and ranking tools.
+ * @module dsh-plugin-hub
+ */
+import Schema from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { PluginHubClient, normalizePluginHubBaseUrl, pluginHubCategories, pluginHubLocales, pluginHubSorts, pluginHubSources, pluginHubTypes, } from './api.js';
+import { rankingLabel, renderPluginHubResult } from './render.js';
+import { pluginHubResultSchema } from './tool-schema.js';
+export const name = 'dsh-plugin-hub';
+export const inject = ['tools'];
+/** Validated plugin configuration. */
+export const Config = Schema.object({
+    baseUrl: Schema.string().default('https://dshpluginhub.dev'),
+    locale: Schema.union(pluginHubLocales).default('en'),
+    timeoutMs: Schema.number().step(1).min(1).max(120_000).default(15_000),
+    maxResults: Schema.number().step(1).min(1).max(50).default(10),
+});
+function boundedInteger(name, value, fallback, maximum) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < 1 || resolved > maximum) {
+        throw new Error(`${name} must be an integer from 1 to ${maximum}`);
+    }
+    return resolved;
+}
+/**
+ * Register the read-only search and ranking tools.
+ * @param ctx - Cordis context carrying the Harness tool registry.
+ * @param config - Validated service and result bounds.
+ */
+export function apply(ctx, config) {
+    const client = new PluginHubClient({
+        baseUrl: normalizePluginHubBaseUrl(config.baseUrl),
+        timeoutMs: config.timeoutMs,
+    });
+    ctx.tools.register(defineTool({
+        name: 'dsh_plugin_search',
+        description: 'Search published and verified DeepSeek Harness plugins by task, feature, plugin name, repository, or author. Returns install commands, compatibility, metrics, and source links.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'What the user needs, or a plugin/author/repository name. Maximum 100 characters.' },
+            locale: { type: 'string', enum: [...pluginHubLocales], description: `Localized descriptions; defaults to ${config.locale}.` },
+            category: { type: 'string', enum: [...pluginHubCategories], description: 'Optional marketplace category.' },
+            type: { type: 'string', enum: [...pluginHubTypes], description: 'Optional host/client/hybrid runtime filter.' },
+            source: { type: 'string', enum: [...pluginHubSources], description: 'Optional npm or GitHub installation source.' },
+            sort: { type: 'string', enum: [...pluginHubSorts], description: 'Ordering; relevance is the default for a non-empty query.' },
+            page: { type: 'integer', description: 'Result page from 1 to 1000; defaults to 1.' },
+            limit: { type: 'integer', description: `Items to return from 1 to ${config.maxResults}; defaults to ${config.maxResults}.` },
+        },
+        output: {
+            schema: pluginHubResultSchema,
+            render: (_args, result) => [{ type: 'text', text: renderPluginHubResult(result, 'Plugin search') }],
+        },
+        async execute(args, exec) {
+            const query = args.query.trim().replace(/\s+/g, ' ');
+            if (!query)
+                throw new Error('query must be a non-empty string');
+            return client.search({
+                query,
+                locale: args.locale ?? config.locale,
+                ...(args.category ? { category: args.category } : {}),
+                ...(args.type ? { type: args.type } : {}),
+                ...(args.source ? { source: args.source } : {}),
+                ...(args.sort ? { sort: args.sort } : {}),
+                page: boundedInteger('page', args.page, 1, 1000),
+                perPage: boundedInteger('limit', args.limit, config.maxResults, config.maxResults),
+            }, exec.signal);
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `Search DSH plugins: ${args.query}`,
+            kind: 'search',
+            rawInput: args,
+        }),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'dsh_plugin_rankings',
+        description: 'List published and verified DeepSeek Harness plugins by daily Star growth, total Stars, newest listing, or recent GitHub activity.',
+        parameters: {
+            ranking: { type: 'string', required: true, enum: ['growth', 'stars', 'newest', 'active'], description: 'growth | stars | newest | active' },
+            locale: { type: 'string', enum: [...pluginHubLocales], description: `Localized descriptions; defaults to ${config.locale}.` },
+            category: { type: 'string', enum: [...pluginHubCategories], description: 'Optional marketplace category.' },
+            page: { type: 'integer', description: 'Result page from 1 to 1000; defaults to 1.' },
+            limit: { type: 'integer', description: `Items to return from 1 to ${config.maxResults}; defaults to ${config.maxResults}.` },
+        },
+        output: {
+            schema: pluginHubResultSchema,
+            render: (args, result) => [{ type: 'text', text: renderPluginHubResult(result, rankingLabel(args.ranking)) }],
+        },
+        async execute(args, exec) {
+            return client.search({
+                locale: args.locale ?? config.locale,
+                ...(args.category ? { category: args.category } : {}),
+                sort: args.ranking,
+                page: boundedInteger('page', args.page, 1, 1000),
+                perPage: boundedInteger('limit', args.limit, config.maxResults, config.maxResults),
+            }, exec.signal);
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: rankingLabel(args.ranking),
+            kind: 'search',
+            rawInput: args,
+        }),
+    }));
+}
+export * from './api.js';
+//# sourceMappingURL=index.js.map

package/dist/render.d.ts

@@ -0,0 +1,11 @@
+import type { PluginHubSearchResult, PluginHubSort } from './api.js';
+/**
+ * Render API results into bounded model-facing discovery text.
+ * @param result - Validated search response.
+ * @param label - Description of the completed operation.
+ * @returns Compact text retaining install and follow-up links.
+ */
+export declare function renderPluginHubResult(result: PluginHubSearchResult, label: string): string;
+/** Human label for one public ranking sort. */
+export declare function rankingLabel(sort: Exclude<PluginHubSort, 'relevance'>): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.js

@@ -0,0 +1,41 @@
+function growth(value) {
+    if (value === null)
+        return '1d growth unavailable';
+    return `1d growth ${value > 0 ? '+' : ''}${value}`;
+}
+function itemLines(plugin, index) {
+    return [
+        `${index + 1}. ${plugin.name} (${plugin.slug})`,
+        `   ${plugin.description}`,
+        `   ${plugin.category} · ${plugin.type} · ${plugin.metrics.stars} stars · ${growth(plugin.metrics.starsDelta1d)}`,
+        `   Install: ${plugin.package.installCommand}`,
+        `   Details: ${plugin.links.detail}`,
+        `   Repository: ${plugin.links.repository}`,
+    ];
+}
+/**
+ * Render API results into bounded model-facing discovery text.
+ * @param result - Validated search response.
+ * @param label - Description of the completed operation.
+ * @returns Compact text retaining install and follow-up links.
+ */
+export function renderPluginHubResult(result, label) {
+    if (result.items.length === 0) {
+        return `${label}: no published, verified plugins matched. Try a broader query or remove a filter.`;
+    }
+    const header = `${label}: ${result.pagination.total} matches; showing ${result.items.length} on page ${result.pagination.page}.`;
+    const quota = result.rateLimit.remaining === null
+        ? null
+        : `Anonymous API quota remaining: ${result.rateLimit.remaining}${result.rateLimit.limit === null ? '' : `/${result.rateLimit.limit}`}.`;
+    return [header, ...result.items.flatMap(itemLines), quota].filter((line) => line !== null).join('\n');
+}
+/** Human label for one public ranking sort. */
+export function rankingLabel(sort) {
+    switch (sort) {
+        case 'growth': return 'Daily growth ranking';
+        case 'stars': return 'Top Stars ranking';
+        case 'newest': return 'Newly listed ranking';
+        case 'active': return 'Recently active ranking';
+    }
+}
+//# sourceMappingURL=render.js.map