dsh-preview-market 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.3
+
+- Catalog entries now live in `catalog/plugins/<owner>__<repo>.json` — one file per plugin, so third parties can submit a PR without editing market code.
+- The Host loads, validates and merges every file at startup; duplicate names and filename/repository mismatches fail fast.
+- `catalog.json` remains the generated machine-readable snapshot; a test keeps it in sync.
+
 ## 0.1.2
 
 - Add a top-level **Settings → Preview market** section, next to dsh-market, with Discover / Installed tabs.

package/README.md

@@ -23,7 +23,9 @@ Upgrading from `dsh-media-preview` / `dsh-blend-preview` / `dsh-stl-preview`? Se
 - **Install / update** — delegates to `dsh-market` when it is present. Without it, the card shows the exact `dsh plugin --profile <profile> add <package>@<version>` command to copy.
 - **Independent plugins** — media, Blender and STL remain separate packages; this page has no renderer and does not merge their code.
 
-## Catalog (0.1.2)
+## Catalog (0.1.3)
+
+Every plugin is **one file** under [`catalog/plugins/`](catalog/plugins/), named `<owner>__<repo>.json`. A third-party submission adds exactly one file plus the regenerated `catalog.json` snapshot — no market code change. The Host loads, validates and merges all files at startup; the format and PR steps are in [`catalog/README.md`](catalog/README.md).
 
 | Package | Formats | Host requirement |
 |---|---|---|
@@ -37,7 +39,7 @@ Settings → Plugins → Preview market (namespace `preview-market`):
 
 | Key | Default | Meaning |
 |---|---|---|
-| `enabled` | `true` | Register the routes and the settings tab. |
+| `enabled` | `true` | Register the routes, the top-level section and the Settings → Plugins tab. |
 | `routeRoot` | `/api/preview-market` | Authenticated route root; must stay under `/api`. |
 | `profileDir` | `""` | Profile to inspect. Empty uses the Host `profileContext`, then `$DSH_HOME/profiles/desktop`. |
 | `debug` | `false` | Reserved for request diagnostics. |
@@ -83,4 +85,4 @@ The client bundle is `lib/client.js` (classic `__ModuleLoader__.load` factory, n
 
 ## Status
 
-`0.1.2` — top-level Settings → Preview market section with Discover / Installed tabs, plus the Settings → Plugins tab. Enable/disable goes through dsh-market. One-click install requires the package in the connected dsh-market registry; otherwise use the copyable command. Configuration stays in each child plugin's own Settings → Plugins page.
+`0.1.3` — top-level Settings → Preview market section with Discover / Installed tabs, plus the Settings → Plugins tab. The catalog is one file per plugin under `catalog/plugins/`, so third-party entries are a one-file PR. Enable/disable goes through dsh-market. One-click install requires the package in the connected dsh-market registry; otherwise use the copyable command. Configuration stays in each child plugin's own Settings → Plugins page.

package/README.zh.md

@@ -23,7 +23,9 @@ dsh plugin --profile <profile> add dsh-preview-market
 - **安装/更新** — 检测到 dsh-market 时委托给它；没有时显示可复制的 `dsh plugin --profile <profile> add <包>@<版本>` 命令。
 - **独立插件** — media、Blender、STL 仍是独立包；本页不注册渲染器，也不合并它们的代码。
 
-## 目录（0.1.2）
+## 目录（0.1.3）
+
+每个插件是 [`catalog/plugins/`](catalog/plugins/) 下的**一个文件**，命名为 `<owner>__<repo>.json`。三方收录只需新增一个文件 + 重新生成 `catalog.json`，不用改市场代码；Host 启动时读取、校验并合并全部文件。字段与 PR 步骤见 [`catalog/README.md`](catalog/README.md)。
 
 | 包 | 格式 | 宿主依赖 |
 |---|---|---|
@@ -33,7 +35,7 @@ dsh plugin --profile <profile> add dsh-preview-market
 
 ## 配置
 
-设置 → 插件 → 预览市场（命名空间 `preview-market`）：
+设置 → 预览市场（命名空间 `preview-market`）：
 
 | 键 | 默认 | 含义 |
 |---|---|---|
@@ -57,4 +59,4 @@ node --test test/*.test.js
 
 ## 状态
 
-`0.1.2` — 顶层「设置 → 预览市场」+ 发现/已安装两个 tab，同时保留「设置 → 插件」里的入口。启用/停用走 dsh-market；一键安装要求对应包已进入所连接 dsh-market 的 registry，否则用可复制命令。配置仍在各子插件自己的 设置 → 插件 页面。
+`0.1.3` — 顶层「设置 → 预览市场」+ 发现/已安装两个 tab，同时保留「设置 → 插件」里的入口。目录改为 `catalog/plugins/` 下一插件一文件，三方收录只需一个文件 PR。启用/停用走 dsh-market；一键安装要求对应包已进入所连接 dsh-market 的 registry，否则用可复制命令。配置仍在各子插件自己的 设置 → 插件 页面。

package/VERIFY.md

@@ -1,15 +1,16 @@
-# Verification record — dsh-preview-market 0.1.2
+# Verification record — dsh-preview-market 0.1.3
 
 ## Unit tests (2026-10-23)
 
-`node --test test/*.test.js` → **10 pass, 0 fail**.
+`node --test test/*.test.js` → **12 pass, 0 fail**.
 
 | File | Covers |
 |---|---|
 | `test/config.test.js` | defaults, `/api` route fence, route normalization, boolean normalization |
-| `test/catalog.test.js` | three catalog entries, required fields, payload shape |
+| `test/catalog.test.js` | one file per entry, required fields, filename/repository match, duplicates, payload shape |
+| `test/catalog-file.test.js` | `catalog.json` snapshot matches the files |
 | `test/installed.test.js` | profile `package.json` + `node_modules` inventory, missing profile, `profileContext` resolution |
-| `test/client.test.js` | bundle registers exactly one `settings.plugins.tab` entry with id `dsh-preview-market` |
+| `test/client.test.js` | bundle registers the `settings.section` and `settings.plugins.tab` entries |
 
 ## Host / bundle smoke (2026-10-23, preview-test profile)
 
@@ -18,6 +19,13 @@
 - The Web boot graph (`__DSH_BOOT__`) contains `dsh-preview-market` and injects `__DSH_PREVIEW_MARKET_CONFIG__`.
 - The combo bundle URL returned **200** (16,213 B) and contains `settings.plugins.tab` + `dsh-preview-market`.
 
+## One-file catalog (2026-10-23)
+
+- Moved the three entries from `lib/catalog.js` into `catalog/plugins/<owner>__<repo>.json`; the Host loads and validates every file at startup.
+- Added a temporary `catalog/plugins/example__dsh-preview-example.json`; `CATALOG` went from 3 to 4 entries without any code change, then was removed.
+- Unit tests (12 pass) validate every file, the filename/repository match, duplicate names, required fields, and the `catalog.json` snapshot.
+- `catalog/README.md` + `.github/PULL_REQUEST_TEMPLATE.md` document the one-file PR.
+
 ## Top-level section e2e (2026-10-23, preview-test)
 
 ```sh

package/catalog/README.md

@@ -0,0 +1,49 @@
+# Preview catalog
+
+One JSON file per plugin. A third-party submission adds **exactly one file** here and opens a PR; nobody edits the market's code.
+
+```
+catalog/plugins/<owner>__<repo>.json
+```
+
+The filename must match the repository URL: `https://github.com/<owner>/<repo>` → `<owner>__<repo>.json`. The Host validates the filename, the required fields, duplicate names and the repository host at startup.
+
+## Entry shape
+
+```json
+{
+  "name": "dsh-preview-example",
+  "npm": "dsh-preview-example",
+  "capability": "example",
+  "kind": "three",
+  "repo": "https://github.com/example/dsh-preview-example",
+  "version": "0.1.0",
+  "minDsh": "0.2.0-rc.2",
+  "requires": [],
+  "extensions": ["example"],
+  "formats": { "model": ["example"] },
+  "description": {
+    "zh": "一句话说明这个预览插件做什么。",
+    "en": "One sentence describing what this preview plugin does."
+  }
+}
+```
+
+Required: `name`, `npm`, `capability`, `kind`, `repo`, `version`, `extensions`, `formats`, `description.zh`, `description.en`.
+
+Optional: `minDsh`, `requires` (defaults to `[]`).
+
+- `kind` is currently `media` or `three`; `three` entries get the shared WebGL viewport.
+- `extensions` drives the document-preview registration in the child plugin; the catalog only displays it.
+- `formats` groups extensions for the card, e.g. `{ "video": [...], "audio": [...] }`.
+
+## Submit a plugin
+
+1. Add `catalog/plugins/<owner>__<repo>.json` with the shape above.
+2. Run `npm test` (it validates every file and the `catalog.json` snapshot).
+3. Run `npm run catalog:write` to regenerate the root `catalog.json` snapshot.
+4. Open a PR that adds **one plugin file plus the regenerated snapshot**.
+
+The plugin itself stays an independent DSH package with its own `dsh.bundle` and repository. Being in this catalog does **not** make one-click install work by itself: the package also has to be present in the connected dsh-market registry; otherwise the market shows the copyable `dsh plugin add` command.
+
+Do not add a plugin to this catalog if it is only a copy of an existing package under another name. The catalog is for distinct preview capabilities.

package/catalog/plugins/439436269-ctrl__dsh-preview-blender.json

@@ -0,0 +1,24 @@
+{
+  "name": "dsh-preview-blender",
+  "npm": "dsh-preview-blender",
+  "capability": "blender",
+  "kind": "three",
+  "repo": "https://github.com/439436269-ctrl/dsh-preview-blender",
+  "version": "0.1.0",
+  "minDsh": "0.2.0-rc.2",
+  "requires": [
+    "blender"
+  ],
+  "extensions": [
+    "blend"
+  ],
+  "formats": {
+    "model": [
+      "blend"
+    ]
+  },
+  "description": {
+    "zh": "Blender 场景：headless 导出缓存 GLB，右侧栏 WebGL 视口 + 对象/三角面/mm 包围盒/材质统计。",
+    "en": "Blender scenes: a cached headless GLB export rendered in a WebGL viewport, with object, triangle, mm-bounds and material statistics."
+  }
+}

package/catalog/plugins/439436269-ctrl__dsh-preview-media.json

@@ -0,0 +1,72 @@
+{
+  "name": "dsh-preview-media",
+  "npm": "dsh-preview-media",
+  "capability": "media",
+  "kind": "media",
+  "repo": "https://github.com/439436269-ctrl/dsh-preview-media",
+  "version": "0.1.4",
+  "minDsh": "0.2.0-rc.2",
+  "requires": [],
+  "extensions": [
+    "mp4",
+    "m4v",
+    "mov",
+    "webm",
+    "ogv",
+    "ogg",
+    "mkv",
+    "avi",
+    "wmv",
+    "flv",
+    "3gp",
+    "ts",
+    "m2ts",
+    "mts",
+    "mp3",
+    "wav",
+    "flac",
+    "m4a",
+    "aac",
+    "oga",
+    "opus",
+    "weba",
+    "wma",
+    "aiff",
+    "aif"
+  ],
+  "formats": {
+    "video": [
+      "mp4",
+      "m4v",
+      "mov",
+      "webm",
+      "ogv",
+      "ogg",
+      "mkv",
+      "avi",
+      "wmv",
+      "flv",
+      "3gp",
+      "ts",
+      "m2ts",
+      "mts"
+    ],
+    "audio": [
+      "mp3",
+      "wav",
+      "flac",
+      "m4a",
+      "aac",
+      "oga",
+      "opus",
+      "weba",
+      "wma",
+      "aiff",
+      "aif"
+    ]
+  },
+  "description": {
+    "zh": "视频与音频：右侧栏原生播放器，HTTP Range 流式读取，桌面端可拖动进度。",
+    "en": "Video and audio in the right-Sidebar document preview, streamed with HTTP Range and seekable in the desktop app."
+  }
+}

package/catalog/plugins/439436269-ctrl__dsh-preview-stl.json

@@ -0,0 +1,22 @@
+{
+  "name": "dsh-preview-stl",
+  "npm": "dsh-preview-stl",
+  "capability": "stl",
+  "kind": "three",
+  "repo": "https://github.com/439436269-ctrl/dsh-preview-stl",
+  "version": "0.1.0",
+  "minDsh": "0.2.0-rc.2",
+  "requires": [],
+  "extensions": [
+    "stl"
+  ],
+  "formats": {
+    "model": [
+      "stl"
+    ]
+  },
+  "description": {
+    "zh": "STL 网格：浏览器解析二进制/ASCII，右侧栏 WebGL 视口 + 尺寸/体积/表面积/水密统计。",
+    "en": "STL meshes: binary/ASCII parsed in the browser, with a WebGL viewport and size, volume, surface-area and watertightness statistics."
+  }
+}

package/catalog.json

@@ -1,6 +1,30 @@
 {
   "schema": 1,
   "plugins": [
+    {
+      "name": "dsh-preview-blender",
+      "npm": "dsh-preview-blender",
+      "capability": "blender",
+      "kind": "three",
+      "repo": "https://github.com/439436269-ctrl/dsh-preview-blender",
+      "version": "0.1.0",
+      "minDsh": "0.2.0-rc.2",
+      "requires": [
+        "blender"
+      ],
+      "extensions": [
+        "blend"
+      ],
+      "formats": {
+        "model": [
+          "blend"
+        ]
+      },
+      "description": {
+        "zh": "Blender 场景：headless 导出缓存 GLB，右侧栏 WebGL 视口 + 对象/三角面/mm 包围盒/材质统计。",
+        "en": "Blender scenes: a cached headless GLB export rendered in a WebGL viewport, with object, triangle, mm-bounds and material statistics."
+      }
+    },
     {
       "name": "dsh-preview-media",
       "npm": "dsh-preview-media",
@@ -73,30 +97,6 @@
         "en": "Video and audio in the right-Sidebar document preview, streamed with HTTP Range and seekable in the desktop app."
       }
     },
-    {
-      "name": "dsh-preview-blender",
-      "npm": "dsh-preview-blender",
-      "capability": "blender",
-      "kind": "three",
-      "repo": "https://github.com/439436269-ctrl/dsh-preview-blender",
-      "version": "0.1.0",
-      "minDsh": "0.2.0-rc.2",
-      "requires": [
-        "blender"
-      ],
-      "extensions": [
-        "blend"
-      ],
-      "formats": {
-        "model": [
-          "blend"
-        ]
-      },
-      "description": {
-        "zh": "Blender 场景：headless 导出缓存 GLB，右侧栏 WebGL 视口 + 对象/三角面/mm 包围盒/材质统计。",
-        "en": "Blender scenes: a cached headless GLB export rendered in a WebGL viewport, with object, triangle, mm-bounds and material statistics."
-      }
-    },
     {
       "name": "dsh-preview-stl",
       "npm": "dsh-preview-stl",

package/lib/catalog.js

@@ -1,75 +1,91 @@
 /**
  * The vertical preview catalog shipped with this release.
  *
- * The catalog is intentionally data-only: adding a new preview plugin should
- * be a catalog entry plus that plugin's own repository, not a change to the
- * market's renderer or routes. Third-party plugins can be added later with the
- * same fields; `dsh.preview` in the installed package is used to enrich the
- * installed view when present.
+ * One JSON file per plugin lives in `catalog/plugins/`; a third-party
+ * submission adds exactly one file and opens a PR. The Host reads and validates
+ * every file at startup, so adding an entry never requires touching this module.
  *
  * @module dsh-preview-market/catalog
  */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /** Catalog schema version. */
 export const CATALOG_SCHEMA = 1;
 
-/** One preview plugin per entry. */
-export const CATALOG = Object.freeze([
-  {
-    name: "dsh-preview-media",
-    npm: "dsh-preview-media",
-    capability: "media",
-    kind: "media",
-    repo: "https://github.com/439436269-ctrl/dsh-preview-media",
-    version: "0.1.4",
-    minDsh: "0.2.0-rc.2",
-    requires: [],
-    extensions: [
-      "mp4", "m4v", "mov", "webm", "ogv", "ogg", "mkv", "avi", "wmv", "flv", "3gp", "ts", "m2ts", "mts",
-      "mp3", "wav", "flac", "m4a", "aac", "oga", "opus", "weba", "wma", "aiff", "aif"
-    ],
-    formats: {
-      video: ["mp4", "m4v", "mov", "webm", "ogv", "ogg", "mkv", "avi", "wmv", "flv", "3gp", "ts", "m2ts", "mts"],
-      audio: ["mp3", "wav", "flac", "m4a", "aac", "oga", "opus", "weba", "wma", "aiff", "aif"]
-    },
-    description: {
-      zh: "视频与音频：右侧栏原生播放器，HTTP Range 流式读取，桌面端可拖动进度。",
-      en: "Video and audio in the right-Sidebar document preview, streamed with HTTP Range and seekable in the desktop app."
-    }
-  },
-  {
-    name: "dsh-preview-blender",
-    npm: "dsh-preview-blender",
-    capability: "blender",
-    kind: "three",
-    repo: "https://github.com/439436269-ctrl/dsh-preview-blender",
-    version: "0.1.0",
-    minDsh: "0.2.0-rc.2",
-    requires: ["blender"],
-    extensions: ["blend"],
-    formats: { model: ["blend"] },
-    description: {
-      zh: "Blender 场景：headless 导出缓存 GLB，右侧栏 WebGL 视口 + 对象/三角面/mm 包围盒/材质统计。",
-      en: "Blender scenes: a cached headless GLB export rendered in a WebGL viewport, with object, triangle, mm-bounds and material statistics."
-    }
-  },
-  {
-    name: "dsh-preview-stl",
-    npm: "dsh-preview-stl",
-    capability: "stl",
-    kind: "three",
-    repo: "https://github.com/439436269-ctrl/dsh-preview-stl",
-    version: "0.1.0",
-    minDsh: "0.2.0-rc.2",
-    requires: [],
-    extensions: ["stl"],
-    formats: { model: ["stl"] },
-    description: {
-      zh: "STL 网格：浏览器解析二进制/ASCII，右侧栏 WebGL 视口 + 尺寸/体积/表面积/水密统计。",
-      en: "STL meshes: binary/ASCII parsed in the browser, with a WebGL viewport and size, volume, surface-area and watertightness statistics."
-    }
+const PLUGIN_DIR = fileURLToPath(new URL("../catalog/plugins/", import.meta.url));
+const REQUIRED = [
+  "name",
+  "npm",
+  "capability",
+  "kind",
+  "repo",
+  "version",
+  "extensions",
+  "formats",
+  "description"
+];
+
+/** Derive `<owner>__<repo>` from a GitHub repository URL. */
+function repoTuple(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`invalid repo URL: ${url}`);
   }
-]);
+  if (parsed.hostname !== "github.com") throw new Error(`repo must be a github.com URL: ${url}`);
+  const parts = parsed.pathname.split("/").filter(Boolean);
+  if (parts.length < 2) throw new Error(`repo must point at a repository: ${url}`);
+  const owner = parts[0];
+  const repo = parts[1].replace(/\.git$/, "");
+  return { owner, repo };
+}
+
+function loadCatalog() {
+  const files = readdirSync(PLUGIN_DIR)
+    .filter((file) => file.endsWith(".json"))
+    .sort();
+  if (files.length === 0) throw new Error("catalog/plugins has no entries");
+
+  const seen = new Set();
+  return Object.freeze(
+    files.map((file) => {
+      let entry;
+      try {
+        entry = JSON.parse(readFileSync(join(PLUGIN_DIR, file), "utf8"));
+      } catch (error) {
+        throw new Error(`catalog/plugins/${file}: invalid JSON (${error.message})`);
+      }
+      for (const key of REQUIRED) {
+        if (entry[key] === undefined) throw new Error(`catalog/plugins/${file}: missing ${key}`);
+      }
+      if (!Array.isArray(entry.extensions) || entry.extensions.length === 0) {
+        throw new Error(`catalog/plugins/${file}: extensions must be a non-empty array`);
+      }
+      if (typeof entry.formats !== "object" || entry.formats === null) {
+        throw new Error(`catalog/plugins/${file}: formats must be an object`);
+      }
+      if (typeof entry.description?.zh !== "string" || typeof entry.description?.en !== "string") {
+        throw new Error(`catalog/plugins/${file}: description.zh/en must be strings`);
+      }
+      if (seen.has(entry.name)) throw new Error(`duplicate catalog name: ${entry.name}`);
+      seen.add(entry.name);
+      entry.requires = Array.isArray(entry.requires) ? entry.requires : [];
+
+      const { owner, repo } = repoTuple(entry.repo);
+      const stem = file.slice(0, -".json".length);
+      if (stem !== `${owner}__${repo}`) {
+        throw new Error(`catalog/plugins/${file}: filename must be ${owner}__${repo}.json`);
+      }
+      return Object.freeze(entry);
+    })
+  );
+}
+
+/** The catalog, loaded from one file per plugin. */
+export const CATALOG = loadCatalog();
 
 /** The catalog payload sent to the browser. */
 export function catalogPayload() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-preview-market",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Vertical preview market for DeepSeek Harness: discover, install and configure preview plugins (media, Blender, STL, ...) from one panel.",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,8 @@
   "files": [
     "lib/**/*.js",
     "catalog.json",
+    "catalog/**/*.json",
+    "catalog/README.md",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md",