dsh-plugin-toolkit 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## 0.13.1
+
+- **A badge you can put on a plugin that passes.** `docs/badge.svg` plus the
+  snippet in both READMEs. It is a claim, not a decoration: the README says to
+  add it only when `verify` exits 0.
+- **Every scaffolded plugin links back.** `init` now writes the badge into the
+  generated README, so a plugin created with the toolkit advertises the toolkit
+  it was checked with.
+- **README badges** for version, downloads, CI and license, and the repository
+  homepage now points at the npm page.
+
+## 0.13.0
+
+Three more rounds of the panel, and one new thing to point it at.
+
+- **The language switch is a real segmented control.** It used to be a bordered
+  box with `overflow: hidden` and a filled button inside it: the fill was clipped
+  by the container's radius and the 0.5px border left a hairline of background
+  along two edges, which read as a missing colour block. Now the track is inset
+  and the selected pill is its own rounded shape, so the fill is complete at
+  every size and in both themes.
+- **A repository name is enough.** The input takes a folder, `owner/repo`, or a
+  GitHub URL. A bare name searches GitHub, lists the matches with their stars
+  and descriptions, and checks the one you click — the picked repository is
+  fetched as a tarball into a temp folder, so nothing is cloned and nothing is
+  installed. Results name the repository and link to it instead of showing a
+  temp path.
+- **Candidates are a list you can act on.** Owner is muted, the repository name
+  carries the weight, an arrow appears on the row, and the rows are keyboard
+  reachable with a visible focus ring.
+- **The guide says what changed.** The "before you trust it" note no longer
+  claims there are no network calls: a local folder is still read-only, a
+  repository is downloaded once, and the note now says so.
+
 ## 0.12.0
 
 Five rounds of the panel's own UI, each one driven by looking at the rendered

package/README.md

@@ -1,5 +1,11 @@
 # dsh-plugin-toolkit
 
+[![npm](https://img.shields.io/npm/v/dsh-plugin-toolkit)](https://www.npmjs.com/package/dsh-plugin-toolkit)
+[![downloads](https://img.shields.io/npm/dw/dsh-plugin-toolkit)](https://www.npmjs.com/package/dsh-plugin-toolkit)
+[![CI](https://github.com/WJDdidi-1/dsh-plugin-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/WJDdidi-1/dsh-plugin-toolkit/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/dsh-plugin-toolkit)](LICENSE)
+
+
 ![dsh-plugin-toolkit](docs/card.png)
 
 English · [中文](./README.zh.md)
@@ -20,10 +26,13 @@ npx dsh-plugin-toolkit@latest release --pr --merge              # tag, wait for
 | changing a panel that is already installed | [`dev`](#2-develop-a-panel) | `mount`, the testkit, `audit` |
 | shipping a version | [`verify`](#3-ship-a-version) | `release`, `index` |
 
-It also installs as a plugin. `dsh plugin add dsh-plugin-toolkit` adds a
-**Plugin doctor** tab to the right sidebar: name the folder that holds a
-plugin's `package.json`, and it runs the same checks `verify` runs and lists
-what would fail — the same answers as the CLI, without leaving the app.
+It also installs as a plugin. `dsh plugin add dsh-plugin-toolkit` puts a
+**插件体检 / Plugin doctor** panel under the conversation and a tab in the right
+sidebar. Give it a folder that holds a plugin's `package.json`, or just
+`owner/repo` — or a repository name, which it searches GitHub for and lists the
+candidates to pick from. It then runs the same checks `verify` runs and says
+which one would break the install, with the reason on the line — the same
+answers as the CLI, without leaving the app.
 
 ```
 $ dsh plugin add dsh-plugin-toolkit
@@ -207,6 +216,16 @@ $ npx dsh-plugin mount ../ai-context-doctor/plugin/client.js
 AIignore No workspace yet Could not read the report …
 ```
 
+## Put the badge on a plugin that passes
+
+If `verify` passes on your plugin, this badge says so and links back here:
+
+```md
+[![checked with dsh-plugin-toolkit](https://raw.githubusercontent.com/WJDdidi-1/dsh-plugin-toolkit/main/docs/badge.svg)](https://github.com/WJDdidi-1/dsh-plugin-toolkit)
+```
+
+It is a claim, not a decoration: add it only when `dsh-plugin verify .` exits 0.
+
 ## Start from the example
 
 [`dsh-plugin-example`](https://github.com/WJDdidi-1/dsh-plugin-example) is a ~70-line plugin: one sidebar tab, two languages, one behaviour test, CI that runs `verify` through the composite action. It is the shape this toolkit expects, so it is also the fastest way to see whether the toolkit fits your plugin. It is a GitHub template too: **Use this template** starts you on a plugin whose first publish already passes.
@@ -297,6 +316,17 @@ forgets `client.js` passes it and fails only after `npm i`.
 cannot state a host range. Pin `version:` if you would rather not track the
 latest release.
 
+## Check a plugin you have not cloned
+
+The panel takes three kinds of input: a folder, `owner/repo`, or a GitHub URL.
+A bare name is a search, not a guess — it asks GitHub, lists the matches with
+their stars, and checks the one you pick. A repository is downloaded once as a
+tarball into a temp folder, so nothing is cloned into your workspace and
+nothing is installed.
+
+The CLI checks local folders only; for a repository, clone it or let the panel
+do the download.
+
 ## What `doctor` checks
 
 | Check | Why it matters |

package/README.zh.md

@@ -36,6 +36,16 @@ npx dsh-plugin-toolkit@latest release --pr --merge              # 打 tag、等
 - Node.js 18 或更新（CI 在 18/20/22 × ubuntu/macos/windows 上跑）。
 - 要发布时需要一个能写 `market/index.json` 的仓库和 `gh`（已登录）。
 
+## 通过检查就挂个徽章
+
+`verify` 过了，可以用这个徽章，点回这里：
+
+```md
+[![checked with dsh-plugin-toolkit](https://raw.githubusercontent.com/WJDdidi-1/dsh-plugin-toolkit/main/docs/badge.svg)](https://github.com/WJDdidi-1/dsh-plugin-toolkit)
+```
+
+这是声明不是装饰：`dsh-plugin verify .` 退出码为 0 才挂。
+
 ## 从一个已经能通过检查的插件开始
 
 ```sh
@@ -57,6 +67,8 @@ cd my-panel && npm install && npm test
 
 检查器固定在**对话栏下方、输入框上方**：默认收起成一行，点开就是完整指南——这是给谁用的、怎么用、每一项检查拦什么、以及它证明不了什么——下面才是文件夹输入框和结果。同一个面板也在右侧栏有一个 **Plugin doctor** 标签页，对话区忙的时候用那个。
 
+输入框接受三种东西：本地文件夹、`owner/repo`、GitHub 链接。**只写一个名字会去 GitHub 搜**，列出候选仓库（带星数），点哪个查哪个；查仓库时只下载一次 tarball 到临时目录，不 clone 进你的工作区、不安装任何东西。
+
 面板中英双语，默认中文；**中文 / EN** 开关就在对话栏那一行的右侧（右侧栏标签里也有），选过之后会记住。
 
 不开应用也能看：

package/client.js

@@ -20,9 +20,10 @@ window.__ModuleLoader__.load({
         fail: 'This would not install cleanly.',
         counts: (failed, total) => `${failed} of ${total} checks failed`,
         passedLabel: (n) => `${n} passed`,
-        empty: 'Paste the folder that holds package.json, then press Check.',
+        empty: 'A folder path, owner/repo, or a GitHub link. A bare name searches GitHub.',
         guideTitle: 'How to use this',
         checkingNow: 'Checking…',
+        candidates: (n) => `${n} repositories match`,
         chipFail: (n) => `${n} failed`,
         chipPass: 'passes',
         checked: 'Checked',
@@ -43,9 +44,10 @@ window.__ModuleLoader__.load({
         fail: '这样装上去会出问题。',
         counts: (failed, total) => `${total} 项里 ${failed} 项没过`,
         passedLabel: (n) => `${n} 项通过`,
-        empty: '粘贴放着 package.json 的文件夹，然后按「检查」。',
+        empty: '填文件夹路径、owner/repo 或 GitHub 链接；只写名字会去 GitHub 搜。',
         guideTitle: '使用说明',
         checkingNow: '正在检查…',
+        candidates: (n) => `找到 ${n} 个仓库`,
         chipFail: (n) => `${n} 项没过`,
         chipPass: '通过',
         checked: '检查的是',
@@ -71,7 +73,7 @@ window.__ModuleLoader__.load({
         steps: {
           title: 'How to use it',
           items: [
-            'Paste the folder that holds the plugin\'s package.json (a folder, not a file).',
+            'Paste a folder, or type owner/repo or a GitHub link. A bare name searches GitHub and lists what it found.',
             'Press Check. Nothing is installed and none of your files are touched.',
             'Read the list: ✓ passes, ✗ would break the install, with one line saying why.',
           ],
@@ -91,7 +93,7 @@ window.__ModuleLoader__.load({
         notes: {
           title: 'Before you trust it',
           items: [
-            'Read-only: it does not install anything, write files, or make network calls beyond this one request.',
+            'It never installs or edits your project. A local folder is read only; a GitHub repository is downloaded once as a tarball and checked in a temp folder.',
             'It looks at a folder, not at what you have installed — use dsh-plugin audit --host … for that.',
             'engines.dsh and README are market-index requirements; a plugin missing them still runs.',
             'It cannot prove runtime behaviour. A panel can still fail inside the real app when a service arrives late or a registration throws; those failures are appended to ~/.dsh/toolkit-client-report.ndjson.',
@@ -110,7 +112,7 @@ window.__ModuleLoader__.load({
         steps: {
           title: '怎么用',
           items: [
-            '粘贴放着 package.json 的那个文件夹（是文件夹，不是文件）。',
+            '填本地文件夹，或 owner/repo、GitHub 链接；只写名字会去 GitHub 搜，列出候选让你挑。',
             '按「检查」。不会安装任何东西，也不会改你的文件。',
             '看列表：✓ 通过，✗ 是装上去会坏的地方，右边一行说明原因。',
           ],
@@ -130,7 +132,7 @@ window.__ModuleLoader__.load({
         notes: {
           title: '用之前要知道的',
           items: [
-            '只读：不安装、不写文件、除这一次请求外不联网。',
+            '不安装、不改你的项目。查本地文件夹时只读；查 GitHub 仓库时会下载一次 tarball，在临时目录里检查。',
             '它看的是文件夹，不是你已装的插件——查已装的用 dsh-plugin audit --host …。',
             'engines.dsh 与 README 是市场索引的要求，缺了插件照样能跑。',
             '它证明不了运行期行为。面板在真实应用里仍可能因为服务来晚了、注册抛错而失败；那些失败会写进 ~/.dsh/toolkit-client-report.ndjson。',
@@ -250,6 +252,25 @@ window.__ModuleLoader__.load({
       '.tk-passes .tk-rows{margin-top:4px}',
       '.tk-summary{display:flex;align-items:baseline;gap:8px;flex-wrap:wrap}',
       '.tk-count{font-size:11px;color:var(--dsw-alias-label-tertiary,#888);font-variant-numeric:tabular-nums}',
+      '.tk-candidates{display:flex;flex-direction:column;gap:6px}',
+      '.tk-candidate-list{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:4px}',
+      '.tk-candidate{display:flex;flex-wrap:wrap;align-items:baseline;gap:6px;width:100%;text-align:left;',
+      'padding:7px 9px;border:0.5px solid var(--dsw-alias-border-l1,#e5e6eb);border-radius:6px;',
+      'background:var(--dsw-alias-bg-body,#fff);font:inherit;cursor:pointer;transition:border-color .12s ease,background .12s ease}',
+      '.tk-candidate:hover{border-color:var(--dsw-alias-state-business-primary,#4176e6);',
+      'background:var(--dsw-alias-bg-layer-1,#fafbfc)}',
+      '.tk-candidate:focus-visible{outline:1px solid var(--dsw-alias-state-business-primary,#4176e6);outline-offset:1px}',
+      '.tk-candidate:hover{border-color:var(--dsw-alias-state-business-primary,#4176e6)}',
+      '.tk-candidate-name{font-size:12px;font-weight:600;min-width:0;overflow:hidden;text-overflow:ellipsis}',
+      '.tk-candidate-owner{font-weight:400;color:var(--dsw-alias-label-tertiary,#888)}',
+      '.tk-candidate-go{margin-left:auto;font-size:12px;color:var(--dsw-alias-label-tertiary,#888)}',
+      '.tk-candidate:hover .tk-candidate-go{color:var(--dsw-alias-state-business-primary,#4176e6)}',
+      '.tk-candidate-stars{font-size:11px;color:var(--dsw-alias-label-tertiary,#888)}',
+      '.tk-candidate-desc{flex-basis:100%;font-size:11px;color:var(--dsw-alias-label-secondary,#555);',
+      'overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+      '.tk-repo{margin:0;font-size:12px}',
+      '.tk-repo a{color:var(--dsw-alias-state-business-primary,#4176e6);text-decoration:none}',
+      '.tk-repo a:hover{text-decoration:underline}',
       '.tk-checked{margin:0;font-size:11px;color:var(--dsw-alias-label-tertiary,#888);overflow-wrap:anywhere}',
       '.tk-checked code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px}',
       '.tk-verdict{margin:0;font-size:12px;font-weight:600}',
@@ -269,11 +290,14 @@ window.__ModuleLoader__.load({
       'color:var(--dsw-alias-label-tertiary,#888)}',
       '.tk-message{font-size:12px;overflow-wrap:anywhere}',
       '.tk-panel-head{display:flex;align-items:center;gap:8px}',
-      '.tk-lang{display:inline-flex;flex:none;border:0.5px solid var(--dsw-alias-border-l2,#ccc);',
-      'border-radius:6px;overflow:hidden}',
-      '.tk-lang-button{height:22px;padding:0 8px;border:0;background:none;font:inherit;font-size:11px;',
-      'color:var(--dsw-alias-label-secondary,#555);cursor:pointer}',
-      '.tk-lang-button[data-on="true"]{background:var(--dsw-alias-state-business-primary,#4176e6);color:#fff}',
+      '.tk-lang{display:inline-flex;flex:none;gap:2px;padding:2px;border-radius:7px;',
+      'background:var(--dsw-alias-bg-layer-1,#f2f3f5)}',
+      '.tk-lang-button{height:20px;min-width:34px;padding:0 8px;border:0;border-radius:5px;background:none;',
+      'font:inherit;font-size:11px;line-height:20px;color:var(--dsw-alias-label-secondary,#555);cursor:pointer;',
+      'transition:background .12s ease,color .12s ease}',
+      '.tk-lang-button[data-on="true"]{background:var(--dsw-alias-state-business-primary,#4176e6);color:#fff;',
+      'box-shadow:0 0 0 0.5px var(--dsw-alias-state-business-primary,#4176e6)}',
+      '.tk-lang-button[data-on="false"]:hover{color:var(--dsw-alias-label-primary,#1f2329)}',
       '.tk-lang-button:focus-visible{outline:1px solid var(--dsw-alias-state-business-primary,#4176e6);outline-offset:-1px}',
       '.tk-dock{border-top:0.5px solid var(--dsw-alias-border-l2,#e5e5e5);margin:0 12px}',
       '.tk-dock-head{display:flex}',
@@ -284,7 +308,10 @@ window.__ModuleLoader__.load({
       '.tk-dock-title{font-weight:600}',
       '.tk-dock-sub{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;',
       'color:var(--dsw-alias-label-tertiary,#888)}',
-      '.tk-dock-chevron{flex:none;font-size:12px;color:var(--dsw-alias-label-tertiary,#888)}',
+      '.tk-dock-chevron{flex:none;width:6px;height:6px;margin:0 2px 0 0;border-right:1.5px solid currentColor;',
+      'border-bottom:1.5px solid currentColor;transform:rotate(-45deg);color:var(--dsw-alias-label-tertiary,#888);',
+      'transition:transform .15s ease}',
+      '.tk-dock-chevron[data-open="true"]{transform:rotate(45deg);margin-bottom:3px}',
       '.tk-summary:focus-visible{outline:1px solid var(--dsw-alias-state-business-primary,#4176e6);',
       'outline-offset:2px;border-radius:4px}',
       '.tk-dock-body{display:flex;flex-direction:column;gap:10px;max-width:76ch;padding:2px 2px 14px;',
@@ -338,14 +365,17 @@ window.__ModuleLoader__.load({
       const [busy, setBusy] = useState(false);
       const [failed, setFailed] = useState(null);
 
-      const check = useCallback(() => {
-        if (dir.trim().length === 0) {
+      const check = useCallback((explicit) => {
+        // A candidate button checks a name that is not in the input yet, so the
+        // target can be passed in instead of read from state.
+        const target = typeof explicit === 'string' ? explicit : dir;
+        if (target.trim().length === 0) {
           setFailed(translate('noDir'));
           return;
         }
         setBusy(true);
         setFailed(null);
-        fetch(`/toolkit/check?dir=${encodeURIComponent(dir.trim())}`)
+        fetch(`/toolkit/check?dir=${encodeURIComponent(target.trim())}`)
           .then((response) => (response.ok === true ? response.json() : Promise.reject(new Error(String(response.status)))))
           .then((payload) => setResult(payload))
           .catch((error) => setFailed(`${translate('failed')} · ${error.message}`))
@@ -385,11 +415,33 @@ window.__ModuleLoader__.load({
           ? h('p', { className: 'tk-empty' }, tr('empty'))
           : null,
         checker.result !== null
-          ? h(ResultBody, { result: checker.result, tr, lang })
+          ? h(ResultBody, { result: checker.result, tr, lang, checker })
           : null);
     }
 
-    function ResultBody({ result, tr, lang }) {
+    function Candidates({ result, tr, lang, checker }) {
+      return h('div', { className: 'tk-candidates' },
+        h('p', { className: 'tk-empty' }, COPY[lang].candidates(result.candidates.length)),
+        h('ul', { className: 'tk-candidate-list' }, result.candidates.map((item) => h('li', { key: item.fullName },
+          h('button', {
+            className: 'tk-candidate',
+            type: 'button',
+            onClick: () => {
+              // Picking a candidate is the same request, with a name the host
+              // can resolve without searching again.
+              checker.setDir(item.fullName);
+              checker.check(item.fullName);
+            },
+          },
+            h('span', { className: 'tk-candidate-name' },
+              h('span', { className: 'tk-candidate-owner' }, `${item.fullName.split('/')[0]}/`),
+              item.fullName.split('/')[1]),
+            item.stars > 0 ? h('span', { className: 'tk-candidate-stars' }, `★ ${item.stars}`) : null,
+            h('span', { className: 'tk-candidate-go', 'aria-hidden': 'true' }, '→'),
+            item.description !== '' ? h('span', { className: 'tk-candidate-desc' }, item.description) : null)))));
+    }
+
+    function ResultBody({ result, tr, lang, checker }) {
       const summary = useRef(null);
       // After a check the answer is the thing to read; leaving focus in the
       // input means a screen reader announces nothing.
@@ -402,6 +454,9 @@ window.__ModuleLoader__.load({
       // Failures first: a list that opens with six green lines buries the two
       // that matter below the fold of a docked panel.
       const ordered = [...failed, ...passed];
+      if (result.kind === 'candidates') {
+        return h(Candidates, { result, tr, lang, checker });
+      }
       return h('div', { className: 'tk-result-body' },
         h('div', { className: 'tk-summary', ref: summary, tabIndex: -1,
           'data-ok': result.ok === true ? 'true' : 'false', role: 'status' },
@@ -410,7 +465,13 @@ window.__ModuleLoader__.load({
           failed.length > 0
             ? h('span', { className: 'tk-count' }, COPY[lang].counts(failed.length, checks.length))
             : null),
-        typeof result.dir === 'string' && result.dir !== ''
+        result.repo !== undefined
+          ? h('p', { className: 'tk-repo' },
+            h('a', { href: result.repo.url, target: '_blank', rel: 'noreferrer noopener' }, result.repo.fullName))
+          : null,
+        // A repository's temp folder is an implementation detail; a local path is
+        // the thing the person typed, so that one stays.
+        result.repo === undefined && typeof result.dir === 'string' && result.dir !== ''
           ? h('p', { className: 'tk-checked' },
             h('span', {}, `${tr('checked')} `),
             h('code', {}, result.dir))
@@ -468,7 +529,7 @@ window.__ModuleLoader__.load({
           },
             h('span', { className: 'tk-dock-title' }, translate('dockTitle', lang)),
             h('span', { className: 'tk-dock-sub' }, translate('dockSub', lang)),
-            h('span', { className: 'tk-dock-chevron', 'aria-hidden': 'true' }, open === true ? '▾' : '▸')),
+            h('span', { className: 'tk-dock-chevron', 'data-open': open === true ? 'true' : 'false', 'aria-hidden': 'true' })),
           open !== true && checker.result !== null
             ? h('span', {
               className: 'tk-chip',

package/docs/badge.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="196" height="20" role="img" aria-label="dsh plugin: verify passed">
+  <title>dsh plugin: verify passed</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="196" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="82" height="20" fill="#2f3542"/>
+    <rect x="82" width="114" height="20" fill="#1a7f37"/>
+    <rect width="196" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+    <text x="41" y="15" fill="#010101" fill-opacity=".3">dsh plugin</text>
+    <text x="41" y="14">dsh plugin</text>
+    <text x="139" y="15" fill="#010101" fill-opacity=".3">✓ verify passed</text>
+    <text x="139" y="14">✓ verify passed</text>
+  </g>
+</svg>

package/index.js

@@ -11,6 +11,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { doctor } from './lib/doctor.mjs';
+import { resolveTarget } from './lib/github.mjs';
 import { verify } from './lib/verify.mjs';
 
 export const name = 'dsh-plugin-toolkit';
@@ -115,7 +116,7 @@ async function readBody(req) {
   }
 }
 
-export function apply(ctx) {
+export function apply(ctx, options = {}) {
   const reportHandler = async (req, res) => {
     if (req.method !== 'POST') return sendJson(res, 405, { error: 'method-not-allowed' });
     const body = await readBody(req);
@@ -133,10 +134,32 @@ export function apply(ctx) {
     if (req.method !== 'GET') return sendJson(res, 405, { error: 'method-not-allowed' });
     if (sameOrigin(req) === false) return sendJson(res, 403, { error: 'cross-origin' });
     const url = new URL(req.url, 'http://localhost');
+    const input = url.searchParams.get('dir');
     try {
-      return sendJson(res, 200, await checkPlugin(url.searchParams.get('dir')));
+      // A folder path, `owner/repo`, a GitHub URL, or a bare name to search for.
+      const target = await resolveTarget(input, options.github);
+      if (target.kind === 'empty') {
+        return sendJson(res, 200, { ok: false, kind: 'empty', checks: [{ check: 'dir', ok: false, message: 'nothing to check' }] });
+      }
+      if (target.kind === 'candidates') {
+        return sendJson(res, 200, { ok: false, kind: 'candidates', query: target.query, candidates: target.candidates });
+      }
+      const report = await checkPlugin(target.dir);
+      const answer = { ...report, kind: target.kind };
+      if (target.repo !== undefined) answer.repo = target.repo;
+      return sendJson(res, 200, answer);
     } catch (error) {
-      return sendJson(res, 500, { error: 'check-failed', message: String(error && error.message) });
+      const message = String(error && error.message);
+      // A repository that cannot be fetched is a check result, not a server
+      // fault: the panel has to be able to say which one and why.
+      if (/github|answered \d{3}|rate limit/i.test(message) === true) {
+        return sendJson(res, 200, {
+          ok: false,
+          kind: 'github',
+          checks: [{ check: 'github', ok: false, message }],
+        });
+      }
+      return sendJson(res, 500, { error: 'check-failed', message });
     }
   };
 

package/lib/github.mjs

@@ -0,0 +1,94 @@
+/**
+ * Check a plugin without cloning it first.
+ *
+ * A folder path is not the only thing people have in hand when they wonder
+ * whether a plugin works: they have a name, or a GitHub URL they just saw. This
+ * module turns either into a folder, and says which repositories a bare name
+ * could mean before anything is downloaded.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { run } from './exec.mjs';
+
+const UA = 'dsh-plugin-toolkit';
+
+/**
+ * What the input is asking for. A local path wins over everything: an existing
+ * directory is never a repository name, and guessing otherwise would send a
+ * private folder to github.com.
+ */
+export function parseTarget(input) {
+  const raw = typeof input === 'string' ? input.trim() : '';
+  if (raw === '') return { kind: 'empty' };
+  // `~/kit` is how a person writes a home folder; `fs.existsSync` would call it
+  // a search and send the name to github.com.
+  const expanded = raw === '~' || raw.startsWith('~/') === true ? path.join(os.homedir(), raw.slice(1)) : raw;
+  if (fs.existsSync(expanded) === true) return { kind: 'local', dir: path.resolve(expanded) };
+
+  const url = raw.match(/^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#?]+)(?:\/.*)?$/i);
+  if (url !== null) {
+    const repo = url[2].replace(/\.git$/i, '');
+    return { kind: 'repo', owner: url[1], repo };
+  }
+  const slug = raw.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/);
+  if (slug !== null) return { kind: 'repo', owner: slug[1], repo: slug[2].replace(/\.git$/i, '') };
+  // A bare name is a search, not a guess: `dsh-plugin-example` is a repository
+  // name and also a word that matches forty of them.
+  return { kind: 'search', query: raw };
+}
+
+function json(response, what) {
+  if (response.ok !== true) {
+    throw new Error(`${what} answered ${response.status}${response.status === 403 ? ' (GitHub rate limit: unauthenticated requests are limited per hour)' : ''}`);
+  }
+  return response.json();
+}
+
+export async function searchRepos(query, { fetchImpl = fetch, limit = 5 } = {}) {
+  const url = `https://api.github.com/search/repositories?q=${encodeURIComponent(query)}+in:name&sort=stars&per_page=${limit}`;
+  const body = await json(await fetchImpl(url, { headers: { 'User-Agent': UA, Accept: 'application/vnd.github+json' } }), 'GitHub search');
+  return (body.items ?? []).map((item) => ({
+    fullName: item.full_name,
+    description: item.description ?? '',
+    stars: item.stargazers_count ?? 0,
+    url: item.html_url,
+  }));
+}
+
+export async function fetchRepo({ owner, repo }, { fetchImpl = fetch, dir, extract = extractTarball } = {}) {
+  const target = dir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-toolkit-gh-'));
+  const tarball = path.join(target, 'repo.tar.gz');
+  const response = await fetchImpl(`https://codeload.github.com/${owner}/${repo}/tar.gz/HEAD`, {
+    headers: { 'User-Agent': UA },
+    redirect: 'follow',
+  });
+  if (response.ok !== true) throw new Error(`github.com/${owner}/${repo} answered ${response.status}`);
+  fs.writeFileSync(tarball, Buffer.from(await response.arrayBuffer()));
+  const root = extract(tarball, path.join(target, 'repo'));
+  fs.rmSync(tarball, { force: true });
+  return { dir: root, repo: { owner, repo, fullName: `${owner}/${repo}`, url: `https://github.com/${owner}/${repo}` } };
+}
+
+/** GitHub tarballs carry one top-level directory; strip it so `package.json` is at the root. */
+function extractTarball(file, into) {
+  fs.mkdirSync(into, { recursive: true });
+  run('tar', ['-xzf', file, '-C', into, '--strip-components=1'], { stdio: 'pipe' });
+  return into;
+}
+
+/**
+ * Everything the check route needs: a folder to check, or the candidates a name
+ * could mean.
+ */
+export async function resolveTarget(input, options = {}) {
+  const parsed = parseTarget(input);
+  if (parsed.kind === 'empty') return { kind: 'empty' };
+  if (parsed.kind === 'local') return { kind: 'local', dir: parsed.dir };
+  if (parsed.kind === 'repo') {
+    const fetched = await fetchRepo(parsed, options);
+    return { kind: 'github', ...fetched };
+  }
+  const candidates = await searchRepos(parsed.query, options);
+  return { kind: 'candidates', query: parsed.query, candidates };
+}

package/lib/init.mjs

@@ -150,7 +150,7 @@ export function files({ name, title = 'My panel', version = '0.1.0' }) {
     'index.js': `export const name = '${name}';\n\n// The host half runs in Node. Most panels need nothing here.\nexport function apply() {}\n`,
     'client.js': client({ name, title }),
     'test/panel.test.mjs': test({ name, title }),
-    'README.md': `# ${slug}\n\n${title} — a panel for DeepSeek Harness.\n\n## Requirements\n\n| What | Version | Why |\n| --- | --- | --- |\n| DeepSeek Harness | >= 0.2.0 | provides \`sidebarRightTabs\` |\n| Node | >= 18 | the host half |\n\n## Develop\n\n\`\`\`sh\nnpm install\nnpm test            # mounts client.js in Node\nnpm run doctor      # checks the manifest before you publish\n\`\`\`\n\n## Install\n\n\`\`\`sh\ndsh plugin add ${name}\n\`\`\`\n`,
+    'README.md': `# ${slug}\n\n${title} — a panel for DeepSeek Harness.\n\n[![checked with dsh-plugin-toolkit](https://raw.githubusercontent.com/WJDdidi-1/dsh-plugin-toolkit/main/docs/badge.svg)](https://github.com/WJDdidi-1/dsh-plugin-toolkit)\n\n## Requirements\n\n| What | Version | Why |\n| --- | --- | --- |\n| DeepSeek Harness | >= 0.2.0 | provides \`sidebarRightTabs\` |\n| Node | >= 18 | the host half |\n\n## Develop\n\n\`\`\`sh\nnpm install\nnpm test            # mounts client.js in Node\nnpm run doctor      # checks the manifest before you publish\n\`\`\`\n\n## Install\n\n\`\`\`sh\ndsh plugin add ${name}\n\`\`\`\n`,
     '.gitignore': 'node_modules/\n',
     '.github/workflows/ci.yml': `name: ci\n\non:\n  push:\n    branches: [main]\n  pull_request:\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node: [18, 20, 22]\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \${{ matrix.node }}\n      - run: npm install\n      - run: npm test\n      # verify, not doctor: doctor reads the working copy, so a \`files\` list\n      # that forgets client.js passes it and the installed plugin has no panel.\n      - uses: WJDdidi-1/dsh-plugin-toolkit@v1\n        with:\n          dir: .\n          version: ${VERSION}\n`,
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.12.0",
-  "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
+  "version": "0.13.1",
+  "description": "Preflight, release and test DeepSeek Harness plugins: check a folder or any GitHub repository, wait for npm to actually serve the version, and keep the market index honest.",
   "type": "module",
   "bin": {
     "dsh-plugin": "bin/dsh-plugin.mjs"
@@ -21,7 +21,8 @@
     "README.md",
     "README.zh.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/badge.svg"
   ],
   "engines": {
     "node": ">=18",
@@ -33,7 +34,8 @@
     "dsh",
     "plugin-tooling",
     "release",
-    "preflight"
+    "preflight",
+    "github"
   ],
   "license": "Apache-2.0",
   "repository": {