dsh-shelfry 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 fkysly and dsh-market contributors
+Copyright (c) 2026 dsh-shelfry contributors
+
+This project is a modified derivative of dsh-market
+(https://github.com/dsh-market/dsh-market), with its catalog source
+replaced by shelfry. The original MIT notice above is retained as the
+license requires.
+
+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.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/logo.svg" width="96" alt="dsh-shelfry logo">
+</p>
 
-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-shelfry
+
+English | [中文](README.zh.md)
+
+A plugin market for DeepSeek Harness, built by modifying
+[dsh-market](https://github.com/dsh-market/dsh-market) and pointing its catalog
+at **shelfry**. On dsh 0.2.1+ it is a tab on the **Plugins** page next to
+**Installed**; older hosts reach it from Settings → **Shelfry Market**.
+Browse, search, one-click install.
+
+This package is **not published to npm**. Install it from the repository.
+
+## Install
+
+```sh
+dsh plugin --profile web add github:shelfry/dsh-shelfry
+```
+
+Then restart `dsh web`. For a profile other than `web`, replace the name:
+
+```sh
+dsh plugin --profile <profile> add github:shelfry/dsh-shelfry
+```
+
+Installing from a git source makes pnpm ask before running build scripts. The
+`client/client.js` bundle is committed, so the market itself needs no build
+step; a prebuilt tarball can be attached to a release if you prefer that route.
+
+On a machine with DSH Desktop, `dsh plugin --profile web` installs into
+`profiles/web`, **not** the profile the desktop app uses. Install through the
+app's **Settings → Plugins** instead.
+
+## Catalog
+
+The plugin list comes from shelfry, fetched live:
+
+```
+https://shelfry.app/data/market-top.json
+```
+
+That file has its own shape (`entries[]` with `i`, `n`, `d`, `s`, `sc`, `t`,
+`vr`, `g`, `cmd`), which is mapped onto the market's internal `Registry` in
+[`src/shelfry-catalog.ts`](src/shelfry-catalog.ts). Both download regions read
+the same URL — shelfry publishes one JSON, so there is no mirror to fall back to
+and the market does not pretend there is.
+
+To point it somewhere else, set `DSHM_REGISTRY_URL` in the environment dsh runs
+in. Overrides replace the source list rather than heading it.
+
+## Configuration
+
+All settings live under `config:` in the profile's `cordis.patch.yml` — the
+loader passes only that sub-object to a plugin, so a top-level key is silently
+ignored:
+
+```yaml
+- id: dsh-shelfry
+  name: 'dsh-shelfry'
+  config:
+    allowRestart: false   # hide the restart button (systemd/pm2/launchd)
+    buildEnv:
+      CC: /usr/bin/gcc-11
+      CXX: /usr/bin/g++-11
+```
+
+- `allowRestart` — one-click restart is hidden automatically when this process
+  is systemd's own service process; pm2 and launchd are not detected, so those
+  deployments set this by hand.
+- `buildEnv` — environment for the processes the market spawns (installs,
+  compiles, git). `PATH` and `CI` stay managed by the market.
+- `DSHM_GITHUB_PROXY` — operator-owned GitHub acceleration prefix; disables the
+  matching field in the UI when set.
+
+Most of the rest is edited in the UI: download region, GitHub acceleration,
+release channel, entries (sidebar / Settings / Plugins tab), build environment,
+favorites, groups and per-plugin notes.
+
+## What you get
+
+Browse and search the whole shelfry catalog with category filters, star counts
+and bilingual descriptions that follow your UI language; screenshots and
+comments per card; favorites; groups that switch as a unit; themes that apply
+without a restart; one-click install with live progress; backup and restore
+(local JSON, WebDAV, or a private GitHub Gist); per-plugin update checks with a
+"What changed" link; resilient GitHub routes for the China download region;
+uninstall; hot enable/disable through `cordis.patch.yml`; a one-click restart
+when a change cannot hot-load; an "Adjust plugins" recovery page for a boot that
+did not come back; a sanitized log export; a settings card that manages the
+market itself; and a diagnostics page for load order and conflicts.
+
+Install order: a repo-verified npm package first, then a prebuilt GitHub Release
+tarball, then the full repository source. Build scripts stay blocked by default
+(pnpm ≥10); allowing one is an explicit per-package choice.
+
+## Development
+
+```sh
+npm install
+npm run typecheck   # host, client, tests
+npm test            # vitest, 3000+ specs
+npm run build       # lib/ + client/client.js
+```
+
+`client/client.js` is a committed artifact: rebuild it and commit the result
+with the source change. `scripts/preflight.mjs` (run by `prepack`) checks that
+the loader id in that file matches `package.json`, that
+`cordis.patch.yml` inserts by the same name, and that the declared icon ships.
+
+The browser bundle registers itself as `window.__ModuleLoader__.load({ id })`,
+where the id must equal the package name — a mismatch loads no UI at all.
+
+See [TESTING.md](TESTING.md) for code conventions and [SECURITY.md](SECURITY.md)
+for the security boundary.
+
+## License
+
+MIT. This is a derivative of dsh-market; the original copyright notice is
+retained in [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,112 @@
+<p align="center">
+  <img src="assets/logo.svg" width="96" alt="dsh-shelfry logo">
+</p>
+
+# dsh-shelfry
+
+[English](README.md) | 中文
+
+装在 DeepSeek Harness 里的插件市场。它基于
+[dsh-market](https://github.com/dsh-market/dsh-market) 改造，目录数据换成
+**shelfry**。dsh 0.2.1 起它是 **插件** 页上紧挨着 **已安装** 的一个页签；
+更早的宿主从设置 → **Shelfry 市场** 进入。逛一逛，点一下，装好。
+
+本包**没有发布到 npm**，从仓库安装。
+
+## 安装
+
+```sh
+dsh plugin --profile web add github:shelfry/dsh-shelfry
+```
+
+装完重启 `dsh web`。profile 不是 `web` 的话换个名字：
+
+```sh
+dsh plugin --profile <profile> add github:shelfry/dsh-shelfry
+```
+
+从 git 源安装时，pnpm 会先问是否允许运行构建脚本。`client/client.js` 已经
+随仓库提交，所以市场本身不需要构建；也可以把预构建的 tarball 挂到 release
+上走那条路。
+
+装了 DSH 桌面端的机器上，`dsh plugin --profile web` 装进的是
+`profiles/web`，**不是**桌面端在用的那个 profile。这种情况请用应用里的
+**设置 → 插件** 安装。
+
+## 目录数据
+
+插件列表实时取自 shelfry：
+
+```
+https://shelfry.app/data/market-top.json
+```
+
+这份文件有自己的结构（`entries[]`，字段 `i`、`n`、`d`、`s`、`sc`、`t`、
+`vr`、`g`、`cmd`），由 [`src/shelfry-catalog.ts`](src/shelfry-catalog.ts)
+映射成市场内部的 `Registry`。两个下载地区读同一个地址——shelfry 只公开这一份
+JSON，没有镜像可以退，市场也不做「换一个镜像」的假动作。
+
+想指到别处，在 dsh 运行的环境里设 `DSHM_REGISTRY_URL`。这个覆盖是**替换**
+来源列表，而不是加在队首。
+
+## 配置
+
+所有设置都在 profile 的 `cordis.patch.yml` 的 `config:` 下面——加载器只把
+这个子对象传给插件，写在顶层的键会被静默忽略：
+
+```yaml
+- id: dsh-shelfry
+  name: 'dsh-shelfry'
+  config:
+    allowRestart: false   # 隐藏重启按钮（systemd / pm2 / launchd）
+    buildEnv:
+      CC: /usr/bin/gcc-11
+      CXX: /usr/bin/g++-11
+```
+
+- `allowRestart` —— 本进程是 systemd 的服务主进程时，重启按钮会自动隐藏；
+  pm2 和 launchd 检测不到，这些部署要手动设这一项。
+- `buildEnv` —— 市场拉起的每个进程（安装、编译、git）的环境变量。`PATH` 和
+  `CI` 由市场自己管理，不能覆盖。
+- `DSHM_GITHUB_PROXY` —— 运营方持有的 GitHub 加速前缀；设了它，界面里的对应
+  输入框会变成只读。
+
+其余大部分在界面里改：下载地区、GitHub 加速、更新通道、入口（侧栏 / 设置 /
+插件页签）、构建环境、收藏、分组，以及每个插件的一行备注。
+
+## 它有什么
+
+浏览和搜索整个 shelfry 目录，带分类筛选、星标数和跟随界面语言的简介；每张卡片
+有截图和讨论区；收藏；可以整体开关的分组；装完即生效的主题；一键安装与实时
+进度；备份与恢复（本地 JSON、WebDAV、私有 GitHub Gist）；逐插件检查更新并附
+「更新内容」；中国大陆地区的 GitHub 线路降级；卸载；通过 `cordis.patch.yml`
+热启用/停用；不能热加载时的一键重启；启动失败后的「调整插件」恢复页；脱敏的
+日志导出；管理市场自身的设置卡片；以及查看加载顺序与冲突的诊断页。
+
+安装顺序：仓库校验过的 npm 包优先，其次是作者预构建的 GitHub Release
+tarball，最后才是整仓库源码。构建脚本默认被拦住（pnpm ≥10），放行需要你针对
+单个包明确同意。
+
+## 开发
+
+```sh
+npm install
+npm run typecheck   # 宿主、客户端、测试三份
+npm test            # vitest，3000+ 用例
+npm run build       # lib/ 与 client/client.js
+```
+
+`client/client.js` 是提交进仓库的产物：改了源码要重新构建并一起提交。
+`scripts/preflight.mjs`（由 `prepack` 触发）会检查这个文件里的 loader id 与
+`package.json` 一致、`cordis.patch.yml` 按同一个名字插入，以及声明的图标有没有
+打进去。
+
+浏览器产物以 `window.__ModuleLoader__.load({ id })` 注册自己，id 必须等于包名
+——不一致就一个界面都加载不出来。
+
+代码规范见 [TESTING.md](TESTING.md)，安全边界见 [SECURITY.md](SECURITY.md)。
+
+## 许可
+
+MIT。本项目是 dsh-market 的衍生修改版，原始版权声明保留在
+[LICENSE](LICENSE)。

package/UPDATE-API-V1.md

@@ -0,0 +1,207 @@
+# Public plugin update API v1
+
+> **Status: beta.** The shape described here may still change between
+> releases. `GET /dsh-shelfry/api/v1/capabilities` reports
+> `"stability": "beta"` while that is true, and `"stable"` once it stops
+> moving — read that field rather than assuming from the `v1` in the path.
+>
+> Nothing here is going away; what is not yet promised is that field names
+> and response shapes will survive untouched. If you ship against it now,
+> say so in an issue: a shape somebody depends on is a much stronger reason
+> not to move it, and it is how this reaches `stable`.
+
+
+`dshmarket` exposes a small, versioned, same-origin JSON API for plugin-owned
+update surfaces. It lets a plugin show its own update button without spawning a
+package manager, copying the Market installation algorithm, or binding to the
+Market UI's private response fields.
+
+All responses carry:
+
+```json
+{ "schema": "dsh-shelfry/update-api/v1" }
+```
+
+Clients must discover the API before enabling mutation controls:
+
+```http
+GET /dsh-shelfry/api/v1/capabilities
+```
+
+The response names the Market version, profile, runtime (`web` or `desktop`),
+supported features, restart owner and endpoint paths. A client must hide its
+restart button when `restart.supported` is false. Desktop and supervised hosts
+normally delegate restart to their owning shell or operator.
+
+## Count what can be updated
+
+```http
+GET /dsh-shelfry/api/v1/updates/summary
+```
+
+```json
+{
+  "schema": "dsh-shelfry/update-api/v1",
+  "checked": 12,
+  "updatable": 3,
+  "packages": [
+    { "name": "dsh-mcp-connector", "source": "npm", "installedVersion": "1.1.0", "latestVersion": "1.2.0" }
+  ]
+}
+```
+
+`checked` is the denominator — how many installed plugins the answer looked
+at. Read it, or a badge cannot tell "nothing to update" from "nothing was
+looked at". The two are different answers and only one of them means the
+profile is up to date.
+
+`packages` carries the same objects the single-package endpoint below
+returns, and lists only plugins that can be updated. A badge needs
+`updatable`; a panel needs the rows; neither should have to filter the whole
+profile itself.
+
+`GET /dsh-shelfry/api/v1/capabilities` reports this endpoint at
+`endpoints.updatesSummary` and sets `features.updatesSummary`. Check that
+rather than probing for the path.
+
+## Check one installed package
+
+```http
+GET /dsh-shelfry/api/v1/updates?name=dsh-mcp-connector&force=1
+```
+
+The response includes the installed version, target version, source kind and
+whether the target is a forward update. Omitting `force=1` allows the Market's
+short update-check cache.
+
+## Start and observe an update
+
+Mutation requests require the same-origin protection used by the Market UI.
+
+Every endpoint here — reads included — also sits behind DSH's own browser
+login, on any host that has one (`dsh web` from 0.1.2-alpha.2 on): a request
+without the host's session cookie is answered `401`, and one from an untrusted
+origin `403`, exactly as DSH answers for its own API (#603). A plugin UI running
+in the DSH page sends that cookie with every same-origin `fetch`, so it needs no
+change. A script or tool calling these endpoints from outside the browser is the
+anonymous client this refuses; there is no separate token for it.
+
+```http
+POST /dsh-shelfry/api/v1/updates
+Content-Type: application/json
+
+{ "packageName": "dsh-mcp-connector" }
+```
+
+An accepted request returns HTTP `202` immediately with an `operationId`.
+Passing `"force": true` opts this one operation out of the registry release-age
+wait; clients should offer it only after the normal operation reports
+`RELEASE_TOO_FRESH` or `VERSION_UNCHANGED`.
+
+Poll the operation by id:
+
+```http
+GET /dsh-shelfry/api/v1/operations?operationId=<id>
+```
+
+States are `queued`, `running`, `succeeded`, `failed`, `cancelled` and
+`rolled-back`. Running operations include structured package progress when
+pnpm provides it. Terminal operations include:
+
+- the before and actually installed versions;
+- `refreshRequired` and `restartRequired` outcomes;
+- a stable failure code, bounded user-facing message and retryability;
+- whether a compatibility rollback is currently available.
+
+For npm updates, Market verifies the package version that pnpm actually placed
+on disk before reporting success. This prevents pnpm's release-age policy or a
+lagging registry mirror from silently turning `@latest` into an older or
+unexpected build. A mismatch is restored from the pre-update recovery point
+and reported as one of these stable failures:
+
+- `DOWNGRADE_DETECTED`: the resolved version is older than the version present
+  before the operation; not retryable without a new target.
+- `RESOLVED_VERSION_MISMATCH`: the resolved version is BELOW the registry
+  target checked immediately before installation; retryable after registry or
+  mirror convergence. A version above that target is accepted — `latest` can
+  move forward while the install is still running.
+
+Provider clients should still compare `beforeVersion`, the target they showed
+to the user, and `installedVersion` before offering restart. That independent
+check protects clients connected to another compatible provider implementation.
+
+Up to 50 operation records live in the current Host process. A boot id is
+embedded in every operation id, so a client never mistakes a stale browser
+record for a task belonging to the replacement process.
+
+## Roll back
+
+```http
+POST /dsh-shelfry/api/v1/rollback
+Content-Type: application/json
+
+{ "operationId": "<id>" }
+```
+
+Rollback is intentionally capability- and operation-scoped. It is available
+only when the Market's compatibility verification retained a recovery point;
+a later mutation may supersede it. The normalized result is written back to
+the same operation record.
+
+## Restart
+
+```http
+POST /dsh-shelfry/api/v1/restart
+Content-Type: application/json
+
+{}
+```
+
+This preserves the Market's stricter restart guard: direct loopback,
+same-origin, no forwarding headers, no package mutation in progress, and a Host
+whose lifecycle is not owned by Desktop or a supervisor. Clients must feature
+detect it; they must not invent an alternative process-control path.
+
+## Rendering the market's panel elsewhere (client-side)
+
+A host shell that wants the market inside its own container — rather than in
+the settings page — reads the client service this package publishes:
+
+```ts
+const market = ctx.reflect.get('market')
+const element = market.render({ preferredSubsectionId: 'installed' })
+```
+
+`render()` returns the market's own panel wrapped in its error boundary, as a
+React element. Same page, same React instance: this package's client bundle
+resolves react through the host's module table, so the element mounts
+anywhere in that tree.
+
+| member | |
+|---|---|
+| `version` | `1` |
+| `render(props?)` | the panel element; `preferredSubsectionId` is optional |
+| `setSettingsVisible(visible)` | register or retract the market's own `settings.section` entry |
+| `settingsVisible()` | whether that entry is registered right now |
+
+The user's own entry switches (#1015) are ANDed with this control: a host's
+`setSettingsVisible(true)` cannot override an entry the user turned off, and
+the user cannot turn on an entry the host hides. `settingsVisible()` reports
+the resulting registration, not the host's last request.
+
+`ctx.provide(name, value)` and `ctx.reflect.provide(name, value)` are the
+same call — cordis's `Service.provide` delegates to the reflect layer — so
+either idiom reaches this service.
+
+What `render()` is **not**: a way to rearrange the market. It hands over the
+whole panel, chrome included. Cutting the market into host-fillable regions
+is a different design, and one host asking is not yet evidence that it fits
+anyone else.
+
+## Compatibility policy
+
+- New optional response fields may be added within v1.
+- Existing v1 fields and meanings are not repurposed.
+- A breaking change uses a new path and schema version.
+- When discovery is unavailable, plugin UIs should fall back to opening the
+  Market rather than calling legacy `/dsh-shelfry/*` mutation routes directly.

package/assets/logo.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-labelledby="t">
+  <title id="t">插件箱子</title>
+  <!-- 品牌标记：一只箱子，提手 + 朱红箱盖 + 深色箱体。 -->
+  <rect width="128" height="128" rx="28" fill="#f6f2ea"/>
+  <g>
+    <rect x="50.4" y="9.6" width="27.2" height="20.8" rx="10.4" fill="#2b2620"/>
+    <rect x="8.8" y="30.4" width="110.4" height="19.2" rx="8" fill="#c0392b"/>
+    <rect x="16" y="51.2" width="96" height="59.2" rx="9.6" fill="#2b2620"/>
+  </g>
+</svg>