dsh-plugin-toolkit 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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.
+
+## 0.6.2
+
+- 0.6.1 named the Windows shim but spawned `npm.cmd` directly, which Node 18.20/20.12 reject with `EINVAL` (the fix for CVE-2024-27980). `lib/exec.mjs` now runs through the shell on Windows and quotes each argument; elsewhere nothing changes.
+
+## 0.6.1
+
+- `npm`, `git` and `gh` are `.cmd` shims on Windows; `execFileSync('npm', …)` fails there with `spawnSync npm ENOENT`. One helper (`lib/exec.mjs`) now maps the name, instead of a `shell: true` at every call site. Caught by the Windows CI job that 0.6.0 added tests to.
+
+## 0.6.0
+
+`dsh-plugin verify` — the check that reads the tarball instead of the working copy.
+
+- Packs, installs that tarball into a throwaway directory, and mounts the bundle **from the installed copy**, so "works in the repo, broken after `npm i`" is caught before publishing.
+- Fails when the tarball omits the client bundle (found by convention, so it is not in the `files` check doctor runs) or anything else `package.json` points at.
+- `--no-mount` stops after packing, for plugins whose panel needs a host to be meaningful.
+
 ## 0.5.0
 
 `dsh-plugin init` — scaffolding that already passes the checks people hit after their first publish.

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
@@ -198,6 +233,24 @@ The same checks run as a GitHub Action, so a tag cannot go out on a plugin that
 
 Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged.
 
+## Prove the tarball works, not just the repository
+
+`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.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
+```
+
+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.7.0 verify .
+dsh-plugin verify: stopped at pack
+  ✗ pack: the tarball does not contain client.js, so the installed plugin has no panel
+```
+
 ## What `release` does
 
 `release` runs the sequence in the order that fails cheapest first:
@@ -231,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

@@ -7,17 +7,32 @@ import path from 'node:path';
 
 import { doctor } from './doctor.mjs';
 import { init } from './init.mjs';
+import { verify } from './verify.mjs';
 import { plan, release } from './release.mjs';
 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 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
@@ -46,6 +61,7 @@ function flags(argv) {
     else if (token === '--name') parsed.name = argv[++index];
     else if (token === '--title') parsed.title = argv[++index];
     else if (token === '--force') parsed.force = true;
+    else if (token === '--no-mount') parsed.noMount = true;
     else if (token === '--dest') parsed.dest = argv[++index];
     else if (token === '--entry') parsed.entry = argv[++index];
     else if (token === '--build') parsed.build = argv[++index];
@@ -89,6 +105,18 @@ export async function run(argv, io = console) {
     return 1;
   }
 
+  if (command === 'verify') {
+    const result = await verify({ dir, mount: options.noMount !== true });
+    if (result.ok === true) {
+      io.log(`ok  packed ${result.files.length} file(s), installed the tarball, mounted the panel`);
+      if (typeof result.text === 'string') io.log(`    ${result.text}`);
+      return 0;
+    }
+    io.error(`dsh-plugin verify: stopped at ${result.stage}`);
+    printFailures(result.failures, io);
+    return 1;
+  }
+
   if (command === 'init') {
     if (options.name === undefined) {
       io.error('dsh-plugin init: --name <package-name> is required');

package/lib/exec.mjs

@@ -0,0 +1,30 @@
+/**
+ * Only the npm family needs care on Windows:
+ *
+ * - `npm`, `npx`, `yarn` and `pnpm` are `.cmd` shims, so the bare name is
+ *   `ENOENT`;
+ * - and since Node 18.20/20.12 a `.cmd` cannot be spawned without a shell
+ *   (`EINVAL`, the fix for CVE-2024-27980).
+ *
+ * `git` and `gh` are real executables (`git.exe`, `gh.exe`) and must *not* get
+ * a `.cmd` suffix — `git.cmd` does not exist.
+ */
+import { execFileSync } from 'node:child_process';
+
+const SHIMS = new Set(['npm', 'npx', 'yarn', 'pnpm']);
+
+export function command(name) {
+  return process.platform === 'win32' && SHIMS.has(name) ? `${name}.cmd` : name;
+}
+
+function quote(argument) {
+  const text = String(argument);
+  return /[\s"]/u.test(text) ? `"${text.replace(/"/g, '\\"')}"` : text;
+}
+
+export function run(name, args, options = {}) {
+  if (process.platform === 'win32' && SHIMS.has(name)) {
+    return execFileSync(command(name), args.map(quote), { ...options, shell: true });
+  }
+  return execFileSync(name, args, options);
+}

package/lib/pr.mjs

@@ -5,18 +5,18 @@
  * Every side effect goes through an injected runner, so the sequence can be
  * asserted without a network, a repository, or a `gh` login.
  */
-import { execFileSync } from 'node:child_process';
+import { run } from './exec.mjs';
 
 // stderr is piped, not inherited: git's "fatal: ambiguous argument" for a tag
 // that does not exist yet and gh's "no checks reported" both arrive there, and
 // both are expected misses that must not read as failures — but they still have
 // to be readable by the caller.
 export function defaultGit(dir) {
-  return (args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  return (args) => run('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
 export function defaultGh(dir) {
-  return (args) => execFileSync('gh', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  return (args) => run('gh', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
 export function branchName(version, prefix = 'market/') {

package/lib/release.mjs

@@ -5,7 +5,7 @@
  * registry, then touch the index — the index entry carries the publish time the
  * registry reported, so writing it earlier would mean guessing.
  */
-import { execFileSync } from 'node:child_process';
+import { run } from './exec.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -18,7 +18,7 @@ function git(dir, args) {
   // stderr is dropped on purpose: `rev-parse` on a tag that does not exist yet is
   // an expected miss, and git prints "fatal: ambiguous argument" for it, which
   // reads like a failure in the middle of a successful release.
-  return execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  return run('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
 export function tagName(version, prefix = 'plugin-v') {

package/lib/verify.mjs

@@ -0,0 +1,140 @@
+/**
+ * `doctor` reads the repository. Users install the tarball.
+ *
+ * `verify` closes that gap: pack it, install the tarball into a throwaway
+ * directory, then mount the bundle *from the installed copy*. The failures this
+ * catches — a `files` list that omits the entry, a patch file that is not
+ * shipped, a bundle that only works next to its source — all pass `doctor`.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { doctor, declaredPaths } from './doctor.mjs';
+import { resolveEntry } from './dev.mjs';
+import { run } from './exec.mjs';
+
+function packJson(dir) {
+  const output = run('npm', ['pack', '--json', '--dry-run'], {
+    cwd: dir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const [document] = JSON.parse(output);
+  return { files: (document.files ?? []).map((entry) => entry.path), filename: document.filename, size: document.size };
+}
+
+function packTarball(dir, destination) {
+  const output = run('npm', ['pack', '--pack-destination', destination, '--json'], {
+    cwd: dir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const [document] = JSON.parse(output);
+  return path.join(destination, document.filename);
+}
+
+export async function verify({ dir, mount = true }) {
+  const failures = [];
+  const report = doctor(dir);
+  for (const failure of report.failures) failures.push(failure);
+  if (failures.length > 0) return { ok: false, stage: 'doctor', failures, files: [] };
+
+  let packed;
+  try {
+    packed = packJson(dir);
+  } catch (error) {
+    return {
+      ok: false,
+      stage: 'pack',
+      failures: [{ check: 'pack', message: `npm pack failed: ${String(error.stderr ?? error.message).trim().split('\n').slice(-1)[0]}` }],
+      files: [],
+    };
+  }
+
+  // Everything package.json points at has to be inside the tarball, or the
+  // installed plugin is missing its own code.
+  const shipped = new Set(packed.files);
+  for (const target of declaredPaths(report.manifest)) {
+    if (shipped.has(target) === false) {
+      failures.push({
+        check: 'pack',
+        message: `the tarball does not contain ${target}, so the installed plugin would be missing it`,
+      });
+    }
+  }
+  // The client bundle is usually found by convention (`client.js`), so it is
+  // not in `declaredPaths` — but it still has to be in the tarball.
+  const repoEntry = resolveEntry(dir, report.manifest);
+  if (repoEntry !== null) {
+    const relative = path.relative(dir, repoEntry).split(path.sep).join('/');
+    if (shipped.has(relative) === false) {
+      failures.push({
+        check: 'pack',
+        message: `the tarball does not contain ${relative}, so the installed plugin has no panel`,
+      });
+    }
+  }
+
+  if (failures.length > 0) return { ok: false, stage: 'pack', failures, files: packed.files };
+
+  if (mount === false) return { ok: true, stage: 'pack', failures: [], files: packed.files, size: packed.size };
+
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-plugin-verify-'));
+  let installed;
+  try {
+    const tarball = packTarball(dir, scratch);
+    run('npm', ['install', tarball, '--prefix', path.join(scratch, 'install'), '--no-save', '--ignore-scripts', '--no-audit', '--no-fund'], {
+      cwd: scratch,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    installed = path.join(scratch, 'install', 'node_modules', report.manifest.name);
+  } catch (error) {
+    return {
+      ok: false,
+      stage: 'install',
+      failures: [{ check: 'install', message: `installing the tarball failed: ${String(error.stderr ?? error.message).trim().split('\n').slice(-1)[0]}` }],
+      files: packed.files,
+    };
+  }
+
+  if (fs.existsSync(installed) === false) {
+    return {
+      ok: false,
+      stage: 'install',
+      failures: [{ check: 'install', message: `the tarball installed no package at ${report.manifest.name}` }],
+      files: packed.files,
+    };
+  }
+
+  // Same convention the host uses: dsh.client.entry, then client.js.
+  const entryFile = resolveEntry(installed, report.manifest);
+  if (entryFile !== null) {
+    if (fs.existsSync(entryFile) === false) {
+      return {
+        ok: false,
+        stage: 'install',
+        failures: [{ check: 'install', message: `the installed copy has no ${path.basename(entryFile)}` }],
+        files: packed.files,
+      };
+    }
+    try {
+      const { mountClient } = await import('./testkit/index.mjs');
+      const panel = await mountClient({ file: entryFile });
+      const text = panel.text();
+      await panel.unmount();
+      return { ok: true, stage: 'mount', failures: [], files: packed.files, size: packed.size, installed, text };
+    } catch (error) {
+      return {
+        ok: false,
+        stage: 'mount',
+        failures: [{ check: 'mount', message: `the installed bundle does not mount: ${error.message}` }],
+        files: packed.files,
+        installed,
+      };
+    }
+  }
+
+  return { ok: true, stage: 'install', failures: [], files: packed.files, size: packed.size, installed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.5.0",
+  "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": {