@deepseek-ai/dsh-plugin-detail 0.0.0-stage → 0.2.2-alpha.3

package/LICENSE

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

@@ -0,0 +1,46 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/plugin-detail/README.md
+/:
+  en: 505fd12717a89948
+  zh: 2ad120714356f61b
+/dsh-plugin-detail:
+  en: 9ef51ea35aa9ea60
+  zh: 341593614dac3945
+/dsh-plugin-detail/summary:
+  en: 9a5bdafd69ed0208
+  zh: d436f289724bab19
+/dsh-plugin-detail/table-of-contents:
+  en: cd2a60a905c978d6
+  zh: cc71d387d0cbd442
+/dsh-plugin-detail/use-this-package:
+  en: ccdf3fdf80317f76
+  zh: 023b893b30d1dd5b
+/dsh-plugin-detail/use-this-package/document-order:
+  en: fe28217d182b9174
+  zh: 0a0b4a61ee4009eb
+/dsh-plugin-detail/use-this-package/images:
+  en: abeb7bb1f7695e5e
+  zh: 59b87c9abea17dfb
+/dsh-plugin-detail/use-this-package/file-sources:
+  en: 9542401a7d104851
+  zh: 99f80d2960b77bc8
+/dsh-plugin-detail/use-this-package/image-responses:
+  en: d6e7da207ee7f2fb
+  zh: c7b6acaa4d2839a2
+/dsh-plugin-detail/api:
+  en: ed9c0c624558d944
+  zh: 9373180d9edb1012
+/dsh-plugin-detail/model-experience:
+  en: 60eeeeff73bf48b4
+  zh: cf3e6e1885719d6a
+/dsh-plugin-detail/model-experience/kv-cache-effect:
+  en: 4f0eadf94828e66e
+  zh: 4f8a6ec170ebbfb6
+/dsh-plugin-detail/known-limitations-and-deferred-work:
+  en: 5d8abfbb06761f7f
+  zh: 8515079f96e513bf
+/dsh-plugin-detail/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+---
+description: "Plugin detail document selection without state: the meta.detail or README order, language fallback, image paths, and local and npm CDN file sources."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-plugin-detail
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Library without state for plugin detail documents, the long Markdown description a plugin's page shows. It owns the order in which a package's document is chosen, the language fallback, image destinations beside a document, and two read-only file sources: a local package directory and a published npm version on public file CDNs. [`plugin-manager`](../../boot/plugin-manager/README.md#bundle-detail-documents) reads profile bundles with it, and [`plugin-market`](../../boot/plugin-market/README.md#plugin-detail-documents) reads market entries with it and adds repository sources.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [API](#api)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+It is a library, not a service or plugin: no `ctx`, no registrations, no state. Reads go through the file source the caller passes.
+
+<a id="document-order"></a>
+### Document order
+
+A plugin's detail document is the first that exists, in this order:
+
+1. **Locale `meta.detail`.** For each language of the chain, the package's `locale/<language>.json` is read, or, when that file does not exist, the same name with an upper-case two-letter region such as `locale/zh-CN.json`. When the file read declares `meta.detail`, that Markdown file is the document; otherwise the next language is tried.
+2. **Package README.** `README.md`, `readme.md`, `Readme.md`, `README.markdown`, or `README`. A source that lists directories takes any letter case of `README`, `README.md`, and `README.markdown`.
+3. **Repository README, market entries only.** The README of the repository directory that the market entry's `repository` names, otherwise the one that the package's `package.json` `repository` names, at the default branch. [`plugin-market`](../../boot/plugin-market/README.md#plugin-detail-documents) reads it; bundle pages in **Plugins** never read a repository.
+
+`readPackageDocument(files, dir, languages, maxBytes, signal)` implements steps 1 and 2 and returns `undefined` when neither applies. `meta.detail` must be a `/`-separated path relative to the package root that ends in `.md` or `.markdown` and has no empty, `.`, or `..` segment, backslash, or URL scheme. A malformed locale file, a malformed `meta.detail`, and a named file that does not exist fail with `DetailFailure` `invalid`; the README is not read in their place.
+
+`languageChain(language)` builds the chain: the language in lower case, each shorter prefix, then English, so `zh-Hans-CN` reads `zh-hans-cn`, `zh-hans`, `zh`, and `en`.
+
+The returned Markdown has no byte order mark and no leading YAML front matter block.
+
+### Images
+
+`detailImage(document, destination)` resolves an image a document writes: relative to the document, or to the root of its files when it starts with `/`; a query or fragment is ignored. It returns the image's path and media type, or `undefined` for a destination that leaves the root, is malformed, or names a type other than PNG, JPEG, GIF, WebP, AVIF, and SVG.
+
+### File sources
+
+- `localFiles(root, revision)` reads a package directory. A path whose real location leaves the directory reads as absent. `revision`, such as the installed version, becomes part of the source's `key`.
+- `npmFiles(name, version, sources, options)` reads a published version from jsDelivr, unpkg, and npmmirror in the given order. A 404 means the package has no such file; a network failure or another status asks the next CDN. `npmFileSourceOrder(configured, preferred)` puts the preferred CDNs that are configured first, in the preferred order, then the other configured ones.
+- `fetchBody(url, maxBytes, signal, options)` reads one HTTP body up to `maxBytes`, following redirects within the URL's origin.
+
+Every read is bounded by the caller's `maxBytes` and fails with `DetailFailure` `too-large` beyond it, or `network` when a source cannot be reached.
+
+### Image responses
+
+`detailImageResponse(outcome, cacheControl)` answers an image route: the image with `cacheControl`, 404 when there is none, or the failure's status (`too-large` 413, `network` 502, `denied` 403, `git-unavailable` 503, `invalid` 400) with the reason as its body and `Cache-Control: no-store`. Every response carries `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`, because an SVG opened directly would otherwise run scripts on the authenticated API origin.
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import {
+  DetailFailure, detailImage, detailImageResponse, languageChain, localFiles, NPM_FILE_SOURCES, npmFiles, npmFileSourceOrder,
+  readPackageDocument,
+} from '@deepseek-ai/dsh-plugin-detail'
+```
+
+`DetailFailureReason` and `NpmFileSource`, which Remote methods of other packages use, are also exported type-only from `@deepseek-ai/dsh-plugin-detail/types`.
+
+`DetailFiles` is the source interface: `read(path, maxBytes, signal)` returns a file's bytes or `undefined`, and `readme(dir, maxBytes, signal)` returns a directory's README. Repository sources implement it in `plugin-market`.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this library selects documents for plugin pages and adds nothing to model requests.
+
+#### KV Cache effect
+
+None.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Public npm only** — the file CDNs serve packages of the public npm registry; packages of other registries have no npm file source.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,101 @@
+---
+description: "无状态的插件详细介绍文档选择：meta.detail 或 README 的顺序、语言回退、图片路径，以及本地和 npm CDN 文件来源。"
+kind: "package-library"
+---
+
+# dsh-plugin-detail
+
+[English](README.md) | 中文
+
+## 概述
+
+用于插件详细介绍文档的无状态库。详细介绍是插件页面显示的较长 Markdown 描述。本包负责选择包文档的顺序、语言回退、文档旁图片的目标路径，以及两种只读文件来源：本地包目录，以及公共文件 CDN 上已发布的 npm 版本。[`plugin-manager`](../../boot/plugin-manager/README.zh.md#bundle-detail-documents) 用它读取 profile 中的组合包，[`plugin-market`](../../boot/plugin-market/README.zh.md#plugin-detail-documents) 用它读取市场条目，并额外提供仓库来源。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [API](#api)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+本包是库，不是服务或插件：没有 `ctx`、没有注册，也没有状态。所有读取都经由调用方传入的文件来源进行。
+
+<a id="document-order"></a>
+### 文档顺序
+
+插件的详细介绍文档是按以下顺序第一个存在的文档：
+
+1. **locale 中的 `meta.detail`。** 对语言链中的每种语言，读取包的 `locale/<language>.json`；该文件不存在时，读取地区部分为大写两字母的同名文件，例如 `locale/zh-CN.json`。读取到的文件声明 `meta.detail` 时，该 Markdown 文件即为文档；否则尝试下一种语言。
+2. **包 README。** `README.md`、`readme.md`、`Readme.md`、`README.markdown` 或 `README`。能列出目录内容的来源接受任意大小写的 `README`、`README.md` 和 `README.markdown`。
+3. **仓库 README，仅限市场条目。** 市场条目的 `repository` 所指仓库目录中的 README；条目没有 `repository` 时，使用包 `package.json` 的 `repository` 所指仓库目录中的 README；均读取默认分支上的文件。[`plugin-market`](../../boot/plugin-market/README.zh.md#plugin-detail-documents) 读取此步；**插件**中的组合包页面从不读取仓库。
+
+`readPackageDocument(files, dir, languages, maxBytes, signal)` 实现第 1 步和第 2 步，两者都不适用时返回 `undefined`。`meta.detail` 必须是相对于包根目录、以 `/` 分隔、以 `.md` 或 `.markdown` 结尾的路径，且不含空段、`.` 或 `..` 段、反斜杠或 URL scheme。locale 文件格式错误、`meta.detail` 格式错误，或指定的文件不存在时，以 `DetailFailure` `invalid` 失败；不会改为读取 README。
+
+`languageChain(language)` 构建语言链：先是小写形式的该语言，然后是每个更短的前缀，最后是英文，因此 `zh-Hans-CN` 依次读取 `zh-hans-cn`、`zh-hans`、`zh` 和 `en`。
+
+返回的 Markdown 不含字节顺序标记（BOM），也不含开头的 YAML front matter 块。
+
+### 图片
+
+`detailImage(document, destination)` 解析文档中引用的图片：相对于该文档；以 `/` 开头时相对于其文件的根目录；查询和片段被忽略。它返回图片的路径和媒体类型；目标路径超出根目录、格式错误，或指定 PNG、JPEG、GIF、WebP、AVIF 和 SVG 之外的类型时，返回 `undefined`。
+
+### 文件来源
+
+- `localFiles(root, revision)` 读取一个包目录。实际位置超出该目录的路径按不存在处理。`revision`（例如已安装的版本）成为该来源 `key` 的一部分。
+- `npmFiles(name, version, sources, options)` 按给定顺序从 jsDelivr、unpkg 和 npmmirror 读取一个已发布版本。404 表示该包没有此文件；网络失败或其他状态码时改为请求下一个 CDN。`npmFileSourceOrder(configured, preferred)` 把已配置的优先 CDN 按优先顺序排在最前，其后是其他已配置的 CDN。
+- `fetchBody(url, maxBytes, signal, options)` 读取一个 HTTP 响应体，最多 `maxBytes`，并跟随该 URL 的 origin 内的重定向。
+
+每次读取都受调用方 `maxBytes` 的限制，超过时以 `DetailFailure` `too-large` 失败；来源无法访问时以 `network` 失败。
+
+### 图片响应
+
+`detailImageResponse(outcome, cacheControl)` 生成图片路由的响应：有图片时返回该图片并带 `cacheControl`；没有图片时返回 404；失败时返回该失败的状态码（`too-large` 为 413、`network` 为 502、`denied` 为 403、`git-unavailable` 为 503、`invalid` 为 400），以失败原因作为响应体，并带 `Cache-Control: no-store`。每个响应都带有 `X-Content-Type-Options: nosniff` 和 `Content-Security-Policy: sandbox`，因为否则直接打开的 SVG 会在已通过认证的 API origin 上运行脚本。
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import {
+  DetailFailure, detailImage, detailImageResponse, languageChain, localFiles, NPM_FILE_SOURCES, npmFiles, npmFileSourceOrder,
+  readPackageDocument,
+} from '@deepseek-ai/dsh-plugin-detail'
+```
+
+`DetailFailureReason` 和 `NpmFileSource` 供其他包的 Remote 方法使用，也从 `@deepseek-ai/dsh-plugin-detail/types` 以仅类型方式导出。
+
+`DetailFiles` 是来源接口：`read(path, maxBytes, signal)` 返回文件的字节或 `undefined`，`readme(dir, maxBytes, signal)` 返回目录的 README。仓库来源在 `plugin-market` 中实现该接口。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本库为插件页面选择文档，不向模型请求添加任何内容。
+
+#### KV Cache 影响
+
+无。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **只支持公共 npm**——文件 CDN 提供公共 npm 注册表中的包；其他注册表中的包没有 npm 文件来源。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>