@czj-git/dsh-plugin-hub 0.1.0

package/LICENSE

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

@@ -0,0 +1,357 @@
+# DSH Plugin Hub plugin
+
+English | [中文](README.md)
+
+Connects the public, read-only [DSH Plugin Hub](https://dshpluginhub.dev) search API to DeepSeek Harness. Agents can discover published and verified plugins, inspect rankings, and receive install commands, compatibility data, community metrics, and source links.
+
+## Capabilities
+
+- `dsh_plugin_search`: search by task, feature, plugin name, repository, or author.
+- `dsh_plugin_rankings`: list daily growth, Top Stars, newly listed, or recently active plugins.
+- Filter localized results by category, runtime type, installation source, ordering, and page.
+- Return concise actionable text in Native mode and the complete structured result in Code Mode.
+- Validate every public API response field and expose pagination, data freshness, and anonymous quota metadata.
+- Honor Harness cancellation, configurable timeouts, 429 retry information, and stable error categories.
+
+The plugin only calls the public `GET /api/v1/plugins/search` endpoint. It requires no API key, reads no user identity, favorites, or private data, and performs no installation or other write operation. Install commands are result data; execution remains governed by the Harness shell, permission, and approval policies.
+
+## Install and run
+
+Install the npm package into the Web profile:
+
+```sh
+dsh plugin --profile web add @czj-git/dsh-plugin-hub
+```
+
+Inspect the composed configuration and start Harness:
+
+```sh
+dsh --profile web --dump-config
+dsh --profile web
+```
+
+## Configuration
+
+The bundle supplies these defaults:
+
+```yaml
+- id: dsh-plugin-hub
+  name: '@czj-git/dsh-plugin-hub'
+  config:
+    baseUrl: https://dshpluginhub.dev
+    locale: en
+    timeoutMs: 15000
+    maxResults: 10
+```
+
+| Field | Type | Default | Constraints and behavior |
+|---|---|---:|---|
+| `baseUrl` | `string` | `https://dshpluginhub.dev` | API origin. It must use HTTP(S), contain no credentials, query, or fragment, and is normalized without a trailing `/`. |
+| `locale` | `zh \| en` | `en` | Description language when a tool call omits `locale`. |
+| `timeoutMs` | `integer` | `15000` | HTTP timeout per request, from 1 to 120000 milliseconds. |
+| `maxResults` | `integer` | `10` | Highest permitted `limit`, from 1 to 50, and the default `limit` for each call. |
+
+Later profile patch layers must restate the complete `config` object because Cordis patching replaces the row value instead of deep-merging it.
+
+## Tool inputs
+
+### `dsh_plugin_search`
+
+Searches published and verified plugins. The tool trims `query` and collapses consecutive whitespace to one space. An empty normalized query fails before any network request.
+
+| Parameter | Required | Type/values | Default | Description |
+|---|---|---|---|---|
+| `query` | Yes | `string` | — | A user need, feature, plugin, author, or repository. It must be non-empty after normalization and contain at most 100 characters. |
+| `locale` | No | `zh`, `en` | Configured `locale` | Selects localized descriptions. |
+| `category` | No | See “Enumerations” | All categories | Restricts the marketplace category. |
+| `type` | No | `host`, `client`, `hybrid` | All types | Restricts the plugin runtime type. |
+| `source` | No | `npm`, `github` | All sources | Restricts the installation source. |
+| `sort` | No | `relevance`, `growth`, `stars`, `newest`, `active` | `relevance` | Selects stable ordering. A non-empty query defaults to relevance. |
+| `page` | No | `integer` | `1` | Result page from 1 to 1000. |
+| `limit` | No | `integer` | Configured `maxResults` | Items on this page, from 1 to `maxResults`; the service limit is 50. |
+
+Example input:
+
+```json
+{
+  "query": "help a text-only agent understand screenshots",
+  "locale": "en",
+  "category": "multimodal-creative",
+  "type": "hybrid",
+  "source": "npm",
+  "sort": "relevance",
+  "page": 1,
+  "limit": 5
+}
+```
+
+Natural-language example:
+
+```text
+Find a DeepSeek Harness plugin that lets a text-only agent analyze screenshots. Prefer npm packages and include the install command.
+```
+
+### `dsh_plugin_rankings`
+
+Lists rankings through the ordering modes of the same public search endpoint. This tool has no keyword, `type`, or `source` parameter.
+
+| Parameter | Required | Type/values | Default | Description |
+|---|---|---|---|---|
+| `ranking` | Yes | `growth`, `stars`, `newest`, `active` | — | Selects the ranking definition. |
+| `locale` | No | `zh`, `en` | Configured `locale` | Selects localized descriptions. |
+| `category` | No | See “Enumerations” | All categories | Ranks only one category. |
+| `page` | No | `integer` | `1` | Result page from 1 to 1000. |
+| `limit` | No | `integer` | Configured `maxResults` | Items on this page, from 1 to `maxResults`. |
+
+Ranking definitions:
+
+| Value | Ranking | Ordering signal |
+|---|---|---|
+| `growth` | Daily growth | GitHub Star change between the two latest successful snapshots. `starsDelta1d` is `null` without a previous snapshot. |
+| `stars` | Top Stars | Total GitHub Stars. |
+| `newest` | Newly listed | First listing time in DSH Plugin Hub. |
+| `active` | Recently active | Latest GitHub push time. |
+
+Example input:
+
+```json
+{
+  "ranking": "stars",
+  "locale": "en",
+  "category": "coding-tools",
+  "page": 1,
+  "limit": 10
+}
+```
+
+## Enumerations
+
+`category` values:
+
+| Value | Meaning |
+|---|---|
+| `agent-workflow` | Agents and workflows |
+| `coding-tools` | Coding and developer tools |
+| `models-data` | Models and data |
+| `ui-experience` | UI and experience |
+| `integrations` | Connections and integrations |
+| `security-governance` | Security and governance |
+| `multimodal-creative` | Multimodal and creative tools |
+| `observability-cost` | Observability and usage |
+| `other` | Other |
+
+`sort` values:
+
+- `relevance`: exact and prefix matches on names, repositories, and authors lead, followed by contains matches and descriptions; Stars and plugin ID keep ties stable.
+- `growth`, `stars`, `newest`, and `active`: use the same definitions as the ranking tool.
+
+## Tool output
+
+Both tools return the same structured value. Code Mode can consume every field. Native mode uses the text projection below to avoid placing a large JSON object in the model context.
+
+### Complete field reference
+
+| Path | Type | Description |
+|---|---|---|
+| `items` | `Plugin[]` | Plugins on the current page. No matches produce `[]`, not an error. |
+| `items[].id` | `string` | Stable public plugin ID. |
+| `items[].slug` | `string` | Public `owner/repository` identifier. |
+| `items[].name` | `string` | Display name. |
+| `items[].owner` | `string` | GitHub repository owner. |
+| `items[].repo` | `string` | GitHub repository name. |
+| `items[].description` | `string` | Description localized for the selected `locale`. |
+| `items[].type` | `host \| client \| hybrid` | Plugin runtime type. |
+| `items[].category` | `string` | Marketplace category enumeration. |
+| `items[].topics` | `string[]` | Repository topics. |
+| `items[].language` | `string` | Primary repository language. |
+| `items[].license` | `string` | License identifier. |
+| `items[].package.name` | `string` | Package or installation target. |
+| `items[].package.version` | `string` | Validated version. |
+| `items[].package.source` | `npm \| github` | Installation source. |
+| `items[].package.sourceSpec` | `string` | Installation specifier pinned to the validated source/version. |
+| `items[].package.installCommand` | `string` | Copyable DSH command. Returning it does not execute it. |
+| `items[].package.profile` | `string` | Recommended Harness profile. |
+| `items[].compatibility.harnessVersion` | `string` | Harness version used or required during validation. |
+| `items[].compatibility.verificationLevel` | `static-checked \| runtime-verified` | Static or runtime verification level. |
+| `items[].compatibility.smokeStatus` | `static-passed \| passed \| manual-step-required \| failed \| not-run` | Smoke-check result. |
+| `items[].compatibility.validatedAt` | `string` | Compatibility validation time. |
+| `items[].metrics.stars` | `integer` | GitHub Stars. |
+| `items[].metrics.starsDelta1d` | `integer \| null` | Star change between the latest two successful snapshots; `null` without a baseline. |
+| `items[].metrics.forks` | `integer` | GitHub Forks. |
+| `items[].metrics.openIssues` | `integer` | GitHub open issues. |
+| `items[].metrics.views` | `integer` | Public DSH Plugin Hub view count. |
+| `items[].timestamps.listedAt` | `string` | First marketplace listing time. |
+| `items[].timestamps.lastPushedAt` | `string` | Latest GitHub push time. |
+| `items[].timestamps.sourceUpdatedAt` | `string` | Latest source-data update time. |
+| `items[].links.detail` | `string` | DSH Plugin Hub detail URL. |
+| `items[].links.repository` | `string` | GitHub repository URL. |
+| `pagination.page` | `integer` | Current page. |
+| `pagination.perPage` | `integer` | Page size returned by the service. |
+| `pagination.total` | `integer` | Total matching plugins. |
+| `pagination.totalPages` | `integer` | Total pages. |
+| `meta.apiVersion` | `v1` | Public API version. |
+| `meta.locale` | `zh \| en` | Effective description locale. |
+| `meta.query` | `string` | Normalized query accepted by the service; rankings normally return an empty string. |
+| `meta.sort` | `string` | Effective ordering. |
+| `meta.dataUpdatedAt` | `string` | Update time of the data used by this response. |
+| `rateLimit.limit` | `integer \| null` | Anonymous limit from the response header; `null` when absent or invalid. |
+| `rateLimit.remaining` | `integer \| null` | Remaining quota from the response header; `null` when absent or invalid. |
+| `rateLimit.reset` | `string \| null` | Raw `RateLimit-Reset` response header. |
+| `rateLimit.retryAfterSeconds` | `integer \| null` | Non-negative integer seconds from `Retry-After`, normally present on 429. |
+
+### Complete structured output example
+
+```json
+{
+  "items": [
+    {
+      "id": "123",
+      "slug": "owner/plugin",
+      "name": "plugin",
+      "owner": "owner",
+      "repo": "plugin",
+      "description": "A verified DeepSeek Harness plugin.",
+      "type": "host",
+      "category": "coding-tools",
+      "topics": ["dsh-plugin", "developer-tools"],
+      "language": "TypeScript",
+      "license": "MIT",
+      "package": {
+        "name": "dsh-plugin-example",
+        "version": "1.0.0",
+        "source": "npm",
+        "sourceSpec": "dsh-plugin-example@1.0.0",
+        "installCommand": "dsh plugin --profile web add dsh-plugin-example",
+        "profile": "web"
+      },
+      "compatibility": {
+        "harnessVersion": "0.1.0-rc.7",
+        "verificationLevel": "runtime-verified",
+        "smokeStatus": "passed",
+        "validatedAt": "2026-08-27T00:00:00.000Z"
+      },
+      "metrics": {
+        "stars": 42,
+        "starsDelta1d": 3,
+        "forks": 4,
+        "openIssues": 1,
+        "views": 20
+      },
+      "timestamps": {
+        "listedAt": "2026-08-20T00:00:00.000Z",
+        "lastPushedAt": "2026-08-26T00:00:00.000Z",
+        "sourceUpdatedAt": "2026-08-27T00:00:00.000Z"
+      },
+      "links": {
+        "detail": "https://dshpluginhub.dev/en/plugins/owner/plugin",
+        "repository": "https://github.com/owner/plugin"
+      }
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "perPage": 5,
+    "total": 1,
+    "totalPages": 1
+  },
+  "meta": {
+    "apiVersion": "v1",
+    "locale": "en",
+    "query": "screenshot analysis",
+    "sort": "relevance",
+    "dataUpdatedAt": "2026-08-27T00:00:00.000Z"
+  },
+  "rateLimit": {
+    "limit": 60,
+    "remaining": 58,
+    "reset": "42",
+    "retryAfterSeconds": null
+  }
+}
+```
+
+### Native mode text example
+
+```text
+Plugin search: 1 matches; showing 1 on page 1.
+1. plugin (owner/plugin)
+   A verified DeepSeek Harness plugin.
+   coding-tools · host · 42 stars · 1d growth +3
+   Install: dsh plugin --profile web add dsh-plugin-example
+   Details: https://dshpluginhub.dev/en/plugins/owner/plugin
+   Repository: https://github.com/owner/plugin
+Anonymous API quota remaining: 58/60.
+```
+
+No matches produce a successful `items: []`. Native mode renders:
+
+```text
+Plugin search: no published, verified plugins matched. Try a broader query or remove a filter.
+```
+
+## Errors and cancellation
+
+Input validation, network failures, public API errors, and response-validation failures end the tool call instead of presenting partial data as success. The underlying client throws `PluginHubApiError` with these programmatic fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | `string` | Stable caller-facing explanation. |
+| `code` | `string` | Local error code or public service error code. |
+| `status` | `integer \| null` | HTTP status, or `null` if no response was received. |
+| `fields` | `Record<string, string>` | Service field errors, or an empty object. |
+| `retryAfterSeconds` | `integer \| null` | Retry delay accepted only from a valid non-negative integer header. |
+
+Local error codes:
+
+| `code` | Condition |
+|---|---|
+| `CANCELLED` | Harness cancelled the active tool call. |
+| `TIMEOUT` | The request exceeded configured `timeoutMs`. |
+| `NETWORK_ERROR` | DNS, TLS, connection, or another network operation failed. |
+| `INVALID_RESPONSE` | The service returned non-JSON data or a successful response missing required fields. |
+| `HTTP_<status>` | An unsuccessful response did not include a recognized public error object. |
+
+Public service codes are preserved, including `INVALID_QUERY` for invalid parameters and `RATE_LIMITED` when anonymous quota is exhausted. A 429 response also reads `Retry-After`.
+
+Programmatic handling example:
+
+```ts
+import { PluginHubApiError, PluginHubClient } from '@czj-git/dsh-plugin-hub/api'
+
+const client = new PluginHubClient({
+  baseUrl: 'https://dshpluginhub.dev',
+  timeoutMs: 15_000,
+})
+
+try {
+  const result = await client.search(
+    { query: 'memory', locale: 'en', page: 1, perPage: 5 },
+    new AbortController().signal,
+  )
+  console.log(result.items)
+} catch (error) {
+  if (error instanceof PluginHubApiError) {
+    console.error(error.code, error.status, error.retryAfterSeconds)
+  }
+}
+```
+
+## Development and verification
+
+```sh
+npm install
+npm run check
+```
+
+`npm run check` runs strict type checking, keyless unit tests, and the production build. GitHub source installs run `prepare` to generate `dist/`; pnpm 10+ asks users to explicitly allow that build script. Publish an npm package or tarball containing prebuilt `dist/` files to avoid install-time build permission.
+
+## Limitations
+
+- The public API currently exposes one search endpoint; the ranking tool uses that endpoint's stable sort modes.
+- Plugin README bodies, comments, favorites, and user data are outside the public API.
+- Returned install commands are not executed and do not prove suitability for every profile; callers should inspect `package.profile` and the compatibility fields.
+- Anonymous limits are service-controlled and may change; the tool reports the actual headers on each response.
+
+## License
+
+MIT