dsh-plugin-toolkit 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.7.0
+
+Documentation, restructured around what you are trying to do rather than what the tool contains.
+
+- README opens with **Three paths** — write a plugin, develop a panel, ship a version — and each path shows the commands it needs.
+- `--help` gives every command one example line that can be pasted as-is, instead of syntax with placeholders.
+- The stale `Roadmap` (which still described `dev` as unbuilt, two releases after it shipped) is replaced by **What is not here yet**: no `npm publish`, no check against a running app, `dev --host` not covered by CI, no Windows test of the watcher.
+- `test/help.test.mjs` keeps all three honest: every command needs an example without placeholders, the three paths must show each command, and the README may not call a shipped feature unbuilt.
+
 ## 0.6.3
 
 - `git` and `gh` are `.exe` on Windows, not `.cmd`; 0.6.2 renamed them too and `git.cmd` does not exist. Only the npm family is a shim now.

package/README.md

@@ -2,19 +2,48 @@
 
 ![dsh-plugin-toolkit](docs/card.png)
 
-A preflight and release tool for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugins, plus the pieces of the publishing ritual that kept going wrong by hand.
+Everything a [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugin needs between `init` and a version the market index accepts: scaffolding, a test harness for the client bundle, a way to see a change without restarting the app, and a release that does not depend on remembering fourteen steps.
 
+```sh
+npx dsh-plugin-toolkit@0.7.0 init ./my-panel --name my-panel   # a plugin that already passes the checks
+npx dsh-plugin-toolkit@0.7.0 verify .                          # pack it, install the tarball, mount the panel
+npx dsh-plugin-toolkit@0.7.0 release --pr --merge              # tag, wait for npm, update the index, open and merge the PR
 ```
-npx dsh-plugin doctor .          # can this plugin be loaded and installed?
-npx dsh-plugin index             # does every market-index version state a host range?
-npx dsh-plugin release --dry-run # what would shipping this version do?
+
+## Three paths
+
+| You are… | Start with | Then |
+| --- | --- | --- |
+| writing your first plugin | [`init`](#1-write-a-plugin) | `doctor`, `verify` |
+| 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` |
+
+### 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.
+
+```sh
+npx dsh-plugin-toolkit@0.7.0 init ./my-panel --name my-panel
+cd my-panel && npm install && npm test && npx dsh-plugin-toolkit@0.7.0 doctor .
 ```
 
-## Requirements
+### 2. Develop a panel
 
-- Node.js 18 or newer (`node --fetch` is used to read the registry; no dependencies)
-- Git and `gh` on `PATH` for the steps that touch GitHub
-- DeepSeek Harness `>=0.2.0` — the version whose market index carries `engines.dsh`, which is what makes the range check meaningful
+A plugin's client code is one file that calls `window.__ModuleLoader__.load({factory})` — there is no module to import, so the usual React test setup does not apply. [`testkit`](#test-a-panel-without-a-browser) supplies the missing half, and [`dev`](#edit-a-plugin-that-is-already-installed) pushes a rebuilt bundle into the running app.
+
+```sh
+npx dsh-plugin-toolkit@0.7.0 mount ./client.js     # what a user would see, without the app
+npx dsh-plugin-toolkit@0.7.0 dev . --host http://127.0.0.1:54133
+```
+
+### 3. Ship a version
+
+`verify` first (it is the only check that reads the tarball), then `release`, which tags, waits for the registry, writes the index entry with the publish time the registry reports, and — with `--pr --merge` — opens and merges the pull request.
+
+```sh
+npx dsh-plugin-toolkit@0.7.0 verify .
+npx dsh-plugin-toolkit@0.7.0 release . --pr --merge
+```
 
 ## Why this exists
 
@@ -24,11 +53,17 @@ Releasing one plugin fifteen times taught me three things the ecosystem's toolin
 2. **The market index is a second release, done by hand.** Each version needs an entry carrying `publishTimestamp` from the registry and `engines.dsh` from the manifest. Forget the range and the index validator rejects the PR with `Engines mismatch` — after the tag is already public.
 3. **Reading a manifest is not the same as checking it.** A plugin can have a valid `package.json` and still be uninstallable: `files` that omit the entry the manifest points at, a bundle patch that does not exist, a README that never states the host range it declares.
 
+## Requirements
+
+- Node.js 18 or newer (the registry is read with `fetch`; no runtime dependencies)
+- Git and `gh` on `PATH` for the steps that touch GitHub
+- DeepSeek Harness `>=0.2.0` — the version whose market index carries `engines.dsh`, which is what makes the range check meaningful
+- For `testkit`: `jsdom`, `react` and `react-dom` as dev dependencies (`npm install --save-dev jsdom react react-dom`)
 
 ## Start from a plugin that already passes
 
 ```sh
-$ npx dsh-plugin-toolkit@0.5.0 init ./my-panel --name my-panel --title "My panel"
+$ npx dsh-plugin-toolkit@0.7.0 init ./my-panel --name my-panel --title "My panel"
 created 8 file(s) in /Users/you/my-panel
   .github/workflows/ci.yml
   .gitignore
@@ -203,7 +238,7 @@ Exit code is `0` when the plugin can be installed and `1` when it cannot, so it
 `doctor` reads your working copy. Users install the tarball, and a `files` list can ship everything except the panel — `doctor` will not notice.
 
 ```sh
-$ npx dsh-plugin-toolkit@0.6.0 verify .
+$ npx dsh-plugin-toolkit@0.7.0 verify .
 ok  packed 5 file(s), installed the tarball, mounted the panel
     My panel This panel came from dsh-plugin init. Clicks: 0
 ```
@@ -211,7 +246,7 @@ ok  packed 5 file(s), installed the tarball, mounted the panel
 It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. When the `files` list drops the panel:
 
 ```sh
-$ npx dsh-plugin-toolkit@0.6.0 verify .
+$ npx dsh-plugin-toolkit@0.7.0 verify .
 dsh-plugin verify: stopped at pack
   ✗ pack: the tarball does not contain client.js, so the installed plugin has no panel
 ```
@@ -249,17 +284,14 @@ Without `--pr` it prints the `git add` / `gh pr create` commands instead of runn
 | 1 | A check failed, or the release stopped (the failing stage is named) |
 | 2 | Unknown command |
 
-## Looking at it without a Harness
-
-The fixtures under `test/fixtures/` are three tiny plugins — one good, one missing its host range, one whose README contradicts its manifest — and the tests run every check against them:
-
-```
-npm test
-```
+## What is not here yet
 
-## Roadmap
+Honest list, so nobody plans around a feature that does not exist:
 
-- `dev`: watch a client bundle and push it to a running app, instead of restarting the app for every change. Needs one probe first: whether the host exposes a channel that accepts a pushed bundle.
+- **No `npm publish`.** `release` pushes the tag and waits for the registry, so publishing stays in the workflow where your token and provenance live. It never holds your npm credentials.
+- **No check against a running app.** `verify` mounts the installed bundle in Node with a stubbed host. It cannot prove the panel appears in a real sidebar — only that the code the tarball ships renders.
+- **`dev --host` is not covered by CI.** The unit tests use a synthetic event stream; the live path is exercised by hand against a running app, on macOS only.
+- **No Windows testing of the `dev` file watcher.** The Windows CI job runs the whole suite, but the watcher is only asserted against a temp directory, not a real profile.
 
 ## License
 

package/lib/cli.mjs

@@ -13,13 +13,26 @@ import { auditVersions, readIndex } from './index-file.mjs';
 
 export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugins
 
-  dsh-plugin doctor [dir]            check the manifest, README and bundle
-  dsh-plugin release [dir] [flags]   tag, wait for npm, update the market index, open the PR
-  dsh-plugin index [dir]             audit every version in market/index.json
-  dsh-plugin mount <client.js>       render a client bundle in Node and print what a user would see
-  dsh-plugin dev [dir] [flags]       copy a rebuilt bundle into the installed plugin and confirm the reload
-  dsh-plugin init <dir> --name <pkg>  scaffold a plugin that already passes doctor
-  dsh-plugin verify [dir]           pack it, install the tarball, mount the installed panel
+  dsh-plugin init <dir> --name <pkg>   scaffold a plugin that already passes doctor
+      dsh-plugin init ./my-panel --name my-panel
+
+  dsh-plugin doctor [dir]              check the manifest, README and bundle
+      dsh-plugin doctor .
+
+  dsh-plugin verify [dir]              pack it, install the tarball, mount the installed panel
+      dsh-plugin verify .
+
+  dsh-plugin mount <client.js>         render a client bundle in Node and print what a user would see
+      dsh-plugin mount ./client.js --html
+
+  dsh-plugin dev [dir] [flags]         copy a rebuilt bundle into the installed plugin and confirm the reload
+      dsh-plugin dev . --host http://127.0.0.1:54133
+
+  dsh-plugin release [dir] [flags]     tag, wait for npm, update the market index, open the PR
+      dsh-plugin release . --pr --merge
+
+  dsh-plugin index [dir]               audit every version in market/index.json
+      dsh-plugin index market/index.json
 
 Flags
   --dry-run                 show the steps without touching anything

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.6.3",
+  "version": "0.7.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.",
   "type": "module",
   "bin": {