dsh-plugin-toolkit 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.8.1
+
+`0.8.0` installed and then did nothing: the loader starts a plugin by importing
+the bare package name, and `exports["."]` still pointed at the CLI, so the row
+had no `apply` to run.
+
+- `exports["."]` is `./index.js`; the CLI keeps `./cli` and `bin`, the testkit
+  keeps `./testkit`.
+- `test/entry.test.mjs` guards the shape: the root export is the plugin, the
+  patch file names the package once as `- insert:`, and every path
+  `package.json` points at is in `files`.
+
+## 0.8.0
+
+The toolkit can now be installed as a plugin, because a tool that cannot be
+installed the way its users install things is asking them to take its word.
+
+- A "Plugin doctor" tab in the right sidebar: name the folder that holds a
+  plugin's `package.json`, and it runs the same checks the market runs
+  (`doctor` plus the pack list) and says which one would fail.
+- `index.js` registers `GET /toolkit/check?dir=`, read-only, same-origin only,
+  and answers with `{ok, dir, checks:[{check, ok, message}]}`.
+- `cordis.patch.yml` and `dsh.bundle` in `package.json`, so `dsh plugin add
+  dsh-plugin-toolkit` installs the panel; the CLI keeps working from the same
+  package.
+- The panel is tested the way a user meets it: `mountClient` on the real
+  `client.js`, with a stub answering the route the host half registers.
+
 ## 0.7.3
 
 The scaffold was two minor versions behind the tool that wrote it.

package/README.md

@@ -18,6 +18,15 @@ npx dsh-plugin-toolkit@0.7.0 release --pr --merge              # tag, wait for n
 | changing a panel that is already installed | [`dev`](#2-develop-a-panel) | `mount`, the testkit |
 | 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.
+
+```
+$ dsh plugin add dsh-plugin-toolkit
+```
+
 ### 1. Write a plugin
 
 [`init`](#start-from-a-plugin-that-already-passes) writes the files whose absence shows up as a failed first publish — `engines.dsh`, the patch file, a `files` list that ships the code, a client bundle, a test for it, and the CI that runs both. `doctor` then checks the same things without writing anything, and [`verify`](#prove-the-tarball-works-not-just-the-repository) checks the tarball instead of the working copy.

package/client.js

@@ -0,0 +1,161 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-plugin-toolkit',
+  factory: (require) => {
+    const module = { exports: {} };
+    const React = require('react');
+    const { useState, useCallback } = React;
+
+    const NS = 'dsh-plugin-toolkit';
+    const KIND = 'toolkit';
+
+    const COPY = {
+      en: {
+        tabTitle: 'Plugin doctor',
+        title: 'Does this plugin survive an install?',
+        hint: 'The checks the market runs, on the folder you name.',
+        placeholder: '/path/to/your-plugin',
+        check: 'Check',
+        checking: 'Checking…',
+        pass: 'Everything the market checks passes.',
+        fail: 'This would not install cleanly.',
+        noDir: 'Name the folder that holds the plugin\'s package.json.',
+        failed: 'Could not run the checks',
+      },
+      zh: {
+        tabTitle: '插件体检',
+        title: '这个插件装上去还能用吗？',
+        hint: '市场会跑的检查，对着你填的文件夹跑一遍。',
+        placeholder: '/path/to/your-plugin',
+        check: '检查',
+        checking: '检查中…',
+        pass: '市场会检查的项都通过了。',
+        fail: '这样装上去会出问题。',
+        noDir: '请填写放着 package.json 的插件文件夹。',
+        failed: '检查没能跑起来',
+      },
+    };
+
+    const h = React.createElement;
+
+    const CSS = [
+      '.tk-panel{padding:16px;display:flex;flex-direction:column;gap:10px;font-size:13px}',
+      '.tk-title{margin:0;font-size:14px;font-weight:600}',
+      '.tk-hint{margin:0;font-size:12px;color:var(--dsw-alias-label-tertiary,#888)}',
+      '.tk-form{display:flex;gap:8px}',
+      '.tk-input{flex:1;min-width:0;height:28px;padding:0 9px;font:inherit;font-size:12px;',
+      'border:0.5px solid var(--dsw-alias-border-l2,#ccc);border-radius:6px;',
+      'background:var(--dsw-alias-bg-layer-1,#fff);color:inherit}',
+      '.tk-input:focus-visible{outline:1px solid var(--dsw-alias-state-business-primary,#4176e6);outline-offset:-1px}',
+      '.tk-button{height:28px;padding:0 12px;border-radius:6px;border:0;cursor:pointer;font:inherit;',
+      'background:var(--dsw-alias-state-business-primary,#4176e6);color:#fff}',
+      '.tk-button:disabled{opacity:.6;cursor:default}',
+      '.tk-failed{margin:0;font-size:12px;color:var(--dsw-alias-state-error-primary,#c0392b)}',
+      '.tk-verdict{margin:0;font-size:12px;font-weight:600}',
+      '.tk-verdict[data-ok="true"]{color:var(--dsw-alias-state-success-primary,#2f855a)}',
+      '.tk-verdict[data-ok="false"]{color:var(--dsw-alias-state-warn-primary,#b7791f)}',
+      '.tk-rows{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:4px}',
+      '.tk-row{display:flex;gap:8px;align-items:baseline;padding:5px 8px;border-radius:6px;',
+      'background:var(--dsw-alias-bg-layer-1,#fafafa)}',
+      '.tk-mark{width:12px;flex:none;font-weight:600}',
+      '.tk-row[data-ok="true"] .tk-mark{color:var(--dsw-alias-state-success-primary,#2f855a)}',
+      '.tk-row[data-ok="false"] .tk-mark{color:var(--dsw-alias-state-error-primary,#c0392b)}',
+      '.tk-body{display:flex;flex-direction:column;gap:1px;min-width:0}',
+      '.tk-check{font-size:11px;text-transform:uppercase;letter-spacing:.04em;',
+      'color:var(--dsw-alias-label-tertiary,#888)}',
+      '.tk-message{font-size:12px;overflow-wrap:anywhere}',
+    ].join('');
+
+    function injectStyles(document) {
+      if (document.getElementById('dsh-plugin-toolkit:styles') !== null) return;
+      const style = document.createElement('style');
+      style.id = 'dsh-plugin-toolkit:styles';
+      style.textContent = CSS;
+      document.head.appendChild(style);
+    }
+
+    function Row({ entry }) {
+      return h(
+        'li',
+        { className: 'tk-row', 'data-ok': entry.ok === true ? 'true' : 'false' },
+        h('span', { className: 'tk-mark', 'aria-hidden': 'true' }, entry.ok === true ? '✓' : '✗'),
+        h('span', { className: 'tk-body' },
+          h('span', { className: 'tk-check' }, entry.check),
+          h('span', { className: 'tk-message' }, entry.message)),
+      );
+    }
+
+    function Panel() {
+      const [dir, setDir] = useState('');
+      const [result, setResult] = useState(null);
+      const [busy, setBusy] = useState(false);
+      const [failed, setFailed] = useState(null);
+      const tr = (key) => {
+        const language = COPY[document.documentElement.lang === 'zh' ? 'zh' : 'en'];
+        return language[key] ?? key;
+      };
+
+      const check = useCallback(() => {
+        if (dir.trim().length === 0) {
+          setFailed(tr('noDir'));
+          return;
+        }
+        setBusy(true);
+        setFailed(null);
+        fetch(`/toolkit/check?dir=${encodeURIComponent(dir.trim())}`)
+          .then((response) => (response.ok === true ? response.json() : Promise.reject(new Error(String(response.status)))))
+          .then((payload) => setResult(payload))
+          .catch((error) => setFailed(`${tr('failed')} · ${error.message}`))
+          .finally(() => setBusy(false));
+      }, [dir]);
+
+      return h('div', { className: 'tk-panel' },
+        h('h2', { className: 'tk-title' }, tr('title')),
+        h('p', { className: 'tk-hint' }, tr('hint')),
+        h('div', { className: 'tk-form' },
+          h('input', {
+            className: 'tk-input',
+            type: 'text',
+            value: dir,
+            placeholder: tr('placeholder'),
+            'aria-label': tr('placeholder'),
+            onChange: (event) => setDir(event.target.value),
+            onKeyDown: (event) => { if (event.key === 'Enter') check(); },
+          }),
+          h('button', {
+            className: 'tk-button',
+            type: 'button',
+            disabled: busy === true,
+            onClick: check,
+          }, busy === true ? tr('checking') : tr('check'))),
+        failed !== null ? h('p', { className: 'tk-failed', role: 'status' }, failed) : null,
+        result !== null
+          ? h('div', { className: 'tk-result' },
+            h('p', { className: 'tk-verdict', 'data-ok': result.ok === true ? 'true' : 'false', role: 'status' },
+              result.ok === true ? tr('pass') : tr('fail')),
+            h('ul', { className: 'tk-rows' }, result.checks.map((entry) => h(Row, { key: entry.check, entry }))))
+          : null);
+    }
+
+    function apply(ctx) {
+      injectStyles(document);
+      ctx.locale.register(NS, COPY);
+      ctx.inject(['sidebarRightTabs', 'sidebarRight'], (tabCtx) => {
+        if (tabCtx.slots === undefined || tabCtx.sidebarRightTabs === undefined) return;
+        tabCtx.effect(() => tabCtx.slots.inject('sidebar.right.pane.tab', () => tabCtx.slots.register({
+          name: 'sidebar.right.pane.tab',
+          key: NS,
+          locale: NS,
+        }, Panel)));
+        tabCtx.effect(() => tabCtx.sidebarRightTabs.register({
+          id: NS,
+          kind: KIND,
+          priority: 'extension',
+          title: () => 'Plugin doctor',
+        }));
+      });
+    }
+
+    module.exports = { apply, name: 'dsh-plugin-toolkit' };
+    return module.exports;
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# The market installs bundles through this patch, so it has to name the entry
+# the way the harness expects: the package, once.
+- insert:
+    - id: dsh-plugin-toolkit
+      name: dsh-plugin-toolkit
+      config: {}

package/index.js

@@ -0,0 +1,111 @@
+/**
+ * The host half: a panel is a promise that something checked your plugin, so
+ * something has to do the checking on the side that can read files.
+ *
+ * Read-only by design. The panel passes a directory, this runs the same
+ * `doctor` and pack-list checks the CLI runs, and answers with what failed and
+ * the command that fixes it. Nothing here writes to the workspace.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { doctor } from './lib/doctor.mjs';
+import { verify } from './lib/verify.mjs';
+
+export const name = 'dsh-plugin-toolkit';
+
+const LIMIT = 400;
+
+function sendJson(res, status, body) {
+  const text = JSON.stringify(body);
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Content-Length', Buffer.byteLength(text));
+  res.end(text);
+}
+
+function readDir(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) return null;
+  const resolved = path.resolve(value.trim());
+  if (resolved.length > LIMIT) return null;
+  try {
+    if (fs.statSync(resolved).isDirectory() === false) return null;
+  } catch {
+    return null;
+  }
+  return resolved;
+}
+
+/** Same-origin only: this route has no authentication of its own. */
+function sameOrigin(req) {
+  const origin = req.headers !== undefined ? req.headers.origin : undefined;
+  if (typeof origin !== 'string' || origin.length === 0) return true;
+  const host = req.headers.host;
+  try {
+    return new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}
+
+export async function checkPlugin(dir) {
+  const target = readDir(dir);
+  if (target === null) {
+    return { ok: false, dir: null, checks: [{ check: 'dir', ok: false, message: 'that is not a directory' }] };
+  }
+  const checks = [];
+  const report = doctor(target);
+  if (report.failures.length === 0) {
+    checks.push({ check: 'manifest', ok: true, message: `${report.manifest.name}@${report.manifest.version}` });
+  }
+  for (const failure of report.failures) {
+    checks.push({ check: failure.check, ok: false, message: failure.message });
+  }
+  // The pack list is the check `doctor` cannot make: it reads the working copy,
+  // so a `files` entry that forgets client.js passes it and ships a plugin with
+  // no panel.
+  const packed = await verify({ dir: target, mount: false });
+  const known = new Set(checks.map((entry) => entry.check));
+  if (packed.ok === true) {
+    checks.push({ check: 'tarball', ok: true, message: `${packed.files.length} file(s)` });
+  } else {
+    for (const failure of packed.failures ?? []) {
+      // `verify` re-runs doctor first; do not say the same thing twice.
+      if (known.has(failure.check) === true) continue;
+      checks.push({ check: failure.check ?? packed.stage, ok: false, message: failure.message });
+    }
+  }
+  return { ok: checks.every((entry) => entry.ok === true), dir: target, checks };
+}
+
+export function apply(ctx) {
+  const checkHandler = async (req, res) => {
+    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');
+    try {
+      return sendJson(res, 200, await checkPlugin(url.searchParams.get('dir')));
+    } catch (error) {
+      return sendJson(res, 500, { error: 'check-failed', message: String(error && error.message) });
+    }
+  };
+
+  let installed = false;
+  const installRoutes = (serviceCtx) => {
+    if (installed) return;
+    const server = serviceCtx !== null && serviceCtx !== undefined ? serviceCtx.webServer : undefined;
+    if (server === null || server === undefined || typeof server.register !== 'function') return;
+    server.register({ kind: 'exact', path: '/toolkit/check', handler: checkHandler });
+    installed = true;
+  };
+
+  const defer = (deps, callback) => {
+    try {
+      if (typeof ctx.inject === 'function') ctx.inject(deps, callback);
+    } catch {
+      // The service may already be mounted on this context.
+    }
+  };
+  defer(['webServer'], (serviceCtx) => installRoutes(serviceCtx));
+  installRoutes(ctx);
+}

package/package.json

@@ -1,24 +1,29 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "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.",
   "type": "module",
   "bin": {
     "dsh-plugin": "bin/dsh-plugin.mjs"
   },
   "exports": {
-    ".": "./lib/cli.mjs",
+    ".": "./index.js",
+    "./cli": "./lib/cli.mjs",
     "./testkit": "./lib/testkit/index.mjs"
   },
   "files": [
     "bin/",
     "lib/",
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=18",
+    "dsh": ">=0.2.0"
   },
   "keywords": [
     "dsh-plugin",
@@ -65,5 +70,11 @@
     "jsdom": "^26.1.0",
     "react": "^19.3.1",
     "react-dom": "^19.3.1"
-  }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "main": "index.js"
 }