dsh-plugin-toolkit 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.1
+
+- `unmount()` now waits one macrotask before the DOM goes away. React schedules work during its own unmount, and closing jsdom first turned that into `ReferenceError: window is not defined` after a passing test. Found by the example plugin's second test.
+- The README links `dsh-plugin-example` and documents that `unmount()` is async.
+
+## 0.3.0
+
+- `dsh-plugin dev`: copy a rebuilt bundle into the installed plugin, then confirm the reload from the host's `/plugins/events` stream. Subscribing happens *before* the write, because a copy made first is reported to nobody.
+- Without `--host` the copy still happens and the tool says the reload is unconfirmed — no guessed port, no false negative.
+- A failed `--build` copies nothing.
+
 ## 0.2.2
 
 - `unmount()` closes the jsdom window, so a panel that polls does not keep the test process alive.

package/README.md

@@ -49,6 +49,8 @@ console.assert(panel.must('[role="status"]').textContent.includes('92'));
 await panel.unmount();
 ```
 
+`unmount()` is async: it lets React finish the work its own unmount schedules before the DOM goes away. Skipping the `await` surfaces as `ReferenceError: window is not defined` *after* the test has already passed, which is a confusing way to learn it.
+
 What you get back: `text()`, `html()`, `query(selector)`, `must(selector)` (throws with the rendered HTML when it misses), `click(selector)`, `type(selector, value)`, `press(selector, key)`, `focus`, `attributes(selector)`, `snapshot(dir, name)` for a normalised DOM baseline, and `host` for assertions about what the bundle registered.
 
 To look at a bundle by hand:
@@ -65,6 +67,41 @@ $ npx dsh-plugin mount ../ai-context-doctor/plugin/client.js
 AIignore No workspace yet Could not read the report …
 ```
 
+## 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 `doctor` 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.
+
+```sh
+dsh plugin add dsh-plugin-example
+```
+
+## Edit a plugin that is already installed
+
+The host already swaps a rebuilt bundle without a page reload: it watches each plugin's entry artifact and reports a `rebuilt` frame on `/plugins/events`. `dev` puts the new file where the host is looking, then **proves** the frame arrived instead of asking you to check by eye.
+
+```sh
+npx dsh-plugin dev . --host http://127.0.0.1:54133
+```
+
+```
+demo-aiignore: /work/plugin/client.js -> ~/.dsh/profiles/desktop/node_modules/dsh-aiignore/client.js
+initial: copied 163647 bytes at 1:18:43 AM
+reloaded dsh-aiignore (rev e0c0230c4fc9)
+watching /work/plugin
+```
+
+That last line is the whole point: the revision came back from the app's own event stream, so "it reloaded" is a fact, not a hope.
+
+| Flag | Meaning |
+|---|---|
+| `--dest <dir>` | write into this installed copy instead of searching `~/.dsh/profiles/*/node_modules/<name>` |
+| `--entry <file>` | copy this file instead of `dsh.client.entry`, `client.js`, `lib/client.js` |
+| `--build <command>` | run this before each copy (a failed build copies nothing) |
+| `--host <url>` | confirm the reload against the app at this URL; without it the copy still happens and the tool says it is unconfirmed |
+| `--once` | copy once and exit, for scripts |
+
+Two things it does not do, because the host does not: React state inside the reloaded plugin is lost, and a failed swap does not roll back to the previous bundle.
+
 ## Use it in CI
 
 The same checks run as a GitHub Action, so a tag cannot go out on a plugin that would not install:

package/lib/cli.mjs

@@ -15,6 +15,7 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
   dsh-plugin release [dir] [flags]   tag, wait for npm, update the market index
   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
 
 Flags
   --dry-run                 show the steps without touching anything
@@ -34,6 +35,13 @@ function flags(argv) {
     else if (token === '--slot') parsed.slot = argv[++index];
     else if (token === '--surface') parsed.surface = argv[++index];
     else if (token === '--html') parsed.html = 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];
+    else if (token === '--host') parsed.host = argv[++index];
+    else if (token === '--once') parsed.once = true;
+    else if (token === '--debounce') parsed.debounce = Number(argv[++index]);
+    else if (token === '--timeout') parsed.timeout = Number(argv[++index]);
     else if (token.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
     else parsed.positional.push(token);
   }
@@ -86,6 +94,21 @@ export async function run(argv, io = console) {
     return problems === 0 ? 0 : 1;
   }
 
+  if (command === 'dev') {
+    const { dev } = await import('./dev.mjs');
+    return dev({
+      dir: path.resolve(options.positional[0] ?? '.'),
+      dest: options.dest,
+      entry: options.entry,
+      build: options.build,
+      host: options.host,
+      once: options.once === true,
+      debounceMs: options.debounce,
+      timeoutMs: options.timeout,
+      io,
+    });
+  }
+
   if (command === 'mount') {
     const file = options.positional[0];
     if (file === undefined) {

package/lib/dev.mjs

@@ -0,0 +1,216 @@
+/**
+ * Editing a plugin that is already installed.
+ *
+ * The host already knows how to swap a rebuilt bundle: it watches each plugin's
+ * entry artifact and reports a `rebuilt` frame on `/plugins/events`, which the
+ * page turns into a fresh mount. So `dev` does not need a new transport — it
+ * needs to put the new file where the host is looking, and then prove the frame
+ * arrived instead of asking the author to check by eye.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const IGNORED = new Set(['node_modules', '.git', 'docs', 'test', 'tests', 'coverage', 'fixtures']);
+
+export function resolveEntry(dir, manifest) {
+  const declared = manifest?.dsh?.client?.entry;
+  const candidates = [declared, 'client.js', 'lib/client.js', 'dist/client.js'].filter((value) => typeof value === 'string');
+  for (const candidate of candidates) {
+    const absolute = path.resolve(dir, candidate);
+    if (fs.existsSync(absolute)) return absolute;
+  }
+  return null;
+}
+
+/** Where the installed copy lives, so the host's watcher sees the change. */
+export function resolveDest(name, { dest, home = path.join(os.homedir(), '.dsh') } = {}) {
+  if (typeof dest === 'string' && dest.length > 0) return path.resolve(dest);
+  const profiles = path.join(home, 'profiles');
+  if (fs.existsSync(profiles) === false) return null;
+  for (const profile of fs.readdirSync(profiles)) {
+    const candidate = path.join(profiles, profile, 'node_modules', name);
+    if (fs.existsSync(candidate) === true) return candidate;
+  }
+  return null;
+}
+
+export function copyEntry({ from, to }) {
+  if (fs.existsSync(from) === false) throw new Error(`${from} does not exist`);
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  // copyFile updates mtime and ctime, which is exactly the revision the host
+  // compares — an identical rebuild still counts as a new one.
+  fs.copyFileSync(from, to);
+  const stat = fs.statSync(to);
+  return { file: to, bytes: stat.size, mtimeMs: stat.mtimeMs };
+}
+
+export function build({ command, cwd, io = console }) {
+  if (typeof command !== 'string' || command.trim() === '') return { ok: true, skipped: true };
+  io.log(`running: ${command}`);
+  const result = spawnSync(command, { cwd, shell: true, stdio: 'inherit' });
+  return { ok: result.status === 0, status: result.status };
+}
+
+/**
+ * Reads the SSE stream until a `rebuilt` frame names this plugin, then closes
+ * the connection. A timeout is reported as such: the file may be fine and the
+ * app simply not running.
+ */
+export async function verifyReload({ host, id, timeoutMs = 6000, fetchImpl = fetch, action }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const url = `${String(host).replace(/\/+$/, '')}/plugins/events`;
+  try {
+    const response = await fetchImpl(url, { headers: { accept: 'text/event-stream' }, signal: controller.signal });
+    if (response.ok !== true) return { ok: false, reason: `GET ${url} answered ${response.status}` };
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let acted = false;
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done === true) break;
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split('\n\n');
+      buffer = frames.pop() ?? '';
+      for (const frame of frames) {
+        const data = frame.split('\n').find((line) => line.startsWith('data: '));
+        if (data === undefined) continue;
+        // The first frame proves the stream is live. Only then is the file
+        // written: a copy made before subscribing can be reported to nobody.
+        if (acted === false && typeof action === 'function') {
+          acted = true;
+          await action();
+        }
+        let payload;
+        try {
+          payload = JSON.parse(data.slice(6));
+        } catch {
+          continue;
+        }
+        if (payload.type !== 'rebuilt') continue;
+        if (JSON.stringify(payload).includes(id) === false) continue;
+        return { ok: true, rev: payload.rev ?? null, frame: payload };
+      }
+    }
+    return { ok: false, reason: 'the stream ended before a rebuilt frame arrived' };
+  } catch (error) {
+    if (error.name === 'AbortError') return { ok: false, reason: `no rebuilt frame for ${id} within ${timeoutMs}ms` };
+    return { ok: false, reason: error.message };
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+export function watchPlugin({ dir, onChange, debounceMs = 200, io = console }) {
+  const timers = new Map();
+  const watcher = fs.watch(dir, { recursive: true }, (event, file) => {
+    if (typeof file !== 'string') return;
+    const parts = file.split(path.sep);
+    if (parts.some((part) => IGNORED.has(part)) === true) return;
+    if (/\.(png|jpg|jpeg|gif|webp|map|log)$/i.test(file) === true) return;
+    clearTimeout(timers.get(file));
+    timers.set(file, setTimeout(() => {
+      timers.delete(file);
+      onChange(file);
+    }, debounceMs));
+  });
+  io.log(`watching ${dir}`);
+  return () => {
+    for (const timer of timers.values()) clearTimeout(timer);
+    watcher.close();
+  };
+}
+
+export async function dev(options) {
+  const {
+    dir,
+    dest: destOption,
+    entry: entryOption,
+    build: buildCommand,
+    host,
+    once = false,
+    debounceMs = 200,
+    timeoutMs = 4000,
+    io = console,
+    fetchImpl = fetch,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  } = options;
+
+  const manifestPath = path.join(dir, 'package.json');
+  if (fs.existsSync(manifestPath) === false) {
+    io.error(`dsh-plugin dev: ${dir} has no package.json`);
+    return 1;
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const source = entryOption === undefined ? resolveEntry(dir, manifest) : path.resolve(dir, entryOption);
+  if (source === null) {
+    io.error('dsh-plugin dev: no client entry found (dsh.client.entry, client.js, lib/client.js)');
+    return 1;
+  }
+  const destDir = resolveDest(manifest.name, { dest: destOption });
+  if (destDir === null) {
+    io.error(`dsh-plugin dev: ${manifest.name} is not installed in any profile; pass --dest`);
+    return 1;
+  }
+  const relative = path.relative(dir, source);
+  const target = path.join(destDir, relative);
+  io.log(`${manifest.name}: ${source} -> ${target}`);
+
+  const sync = async (reason) => {
+    if (buildCommand !== undefined) {
+      const built = build({ command: buildCommand, cwd: dir, io });
+      if (built.ok === false) {
+        io.error(`build failed (exit ${built.status}); nothing copied`);
+        return { ok: false };
+      }
+    }
+    let copied = null;
+    if (typeof host !== 'string' || host.length === 0) {
+      // Without the app's URL there is nothing to confirm against, and a
+      // guessed port would report "not confirmed" for a reload that happened.
+      copied = copyEntry({ from: source, to: target });
+      io.log(`${reason}: copied ${copied.bytes} bytes at ${new Date(copied.mtimeMs).toLocaleTimeString()}`);
+      io.log('pass --host <the URL the app printed> to confirm the reload happened');
+      return { ok: true, verified: { ok: false, reason: 'no host given' } };
+    }
+    const verified = await verifyReload({
+      host,
+      id: manifest.name,
+      timeoutMs,
+      fetchImpl,
+      action: () => {
+        copied = copyEntry({ from: source, to: target });
+        io.log(`${reason}: copied ${copied.bytes} bytes at ${new Date(copied.mtimeMs).toLocaleTimeString()}`);
+      },
+    });
+    if (copied === null) {
+      // The stream never opened, so the copy still has to happen — otherwise a
+      // stopped app would silently mean "nothing was updated".
+      copied = copyEntry({ from: source, to: target });
+      io.log(`${reason}: copied ${copied.bytes} bytes (no stream to confirm with)`);
+    }
+    if (verified.ok === true) io.log(`reloaded ${manifest.name} (rev ${verified.rev})`);
+    else io.log(`copied, but not confirmed: ${verified.reason}`);
+    return { ok: true, verified };
+  };
+
+  if (once === true) {
+    const result = await sync('once');
+    return result.ok === true ? 0 : 1;
+  }
+
+  let stopping = false;
+  const stop = () => {
+    stopping = true;
+  };
+  process.once('SIGINT', stop);
+  const close = watchPlugin({ dir, debounceMs, io, onChange: (file) => { void sync(file); } });
+  await sync('initial');
+  while (stopping === false) await sleep(200);
+  close();
+  return 0;
+}

package/lib/testkit/mount.mjs

@@ -184,7 +184,14 @@ export async function mountClient(options) {
     },
     writeSnapshot: (dir, name) => write(dir, name, root.innerHTML),
     unmount: async () => {
-      await act(async () => clientRoot.unmount());
+      await act(async () => {
+        clientRoot.unmount();
+        // React schedules follow-up work, and a polling panel schedules timers.
+        // One macrotask lets that land while the DOM is still alive; closing the
+        // window first turns it into "ReferenceError: window is not defined"
+        // after the test has already passed.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
       globalThis.fetch = previousFetch;
       restoreGlobals();
       // A panel polls; jsdom's timers and rAF would keep the test process alive

package/package.json

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