dsh-plugin-toolkit 0.8.6 → 0.8.8

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.8.8
+
+- `dev` reads the plugin graph the app sends first, so a plugin the app never
+  loaded is reported as that ("restart the app once after installing it") instead
+  of as a timeout. Found by running `dev` against a real app, not a fake stream.
+
+## 0.8.7
+
+- `panel.aria(selector)` and `panel.expectAria(selector, expected)`: assert what a
+  screen reader reads, and get the attribute that differs named in the failure.
+  A missing attribute reports `nothing` rather than `""`.
+
 ## 0.8.6
 
 - `release --publish`: run `npm publish` locally instead of waiting for a

package/README.md

@@ -135,10 +135,22 @@ First run writes nothing: it tells you to re-run with `UPDATE_SNAPSHOTS=1`, so a
 ### Check what assistive tech sees
 
 ```js
-assert.equal(panel.attributes('[role="tab"][aria-selected="true"]').id, 'tab-protection');
+panel.expectAria('[role="tab"][aria-selected="true"]', { label: 'Protection', selected: 'true' });
 assert.match(panel.must('[role="status"]').textContent, /Score moved 71 → 77/);
 ```
 
+`expectAria()` compares the attributes a screen reader actually reads — `role`,
+`label`, `live`, `selected`, `expanded`, `checked`, `pressed`, `disabled` — and
+names the one that differs:
+
+```
+[aria-live="polite"]: expected aria text to be "9", but it is "0"
+```
+
+A missing attribute is reported as `nothing`, not as an empty string, because
+those are different bugs. `panel.aria(selector)` returns the same object when you
+want to assert on it yourself.
+
 `must()` throws with the rendered markup when the selector misses, which is the difference between "the assertion failed" and "here is what the user actually got".
 
 Every example below is a file in this repository, run by CI, and the output shown is the output it prints:
@@ -205,6 +217,12 @@ 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.
 
+A plugin the running app never loaded cannot be reloaded, and the app says so by leaving it out of the graph it sends first. `dev` reads that graph, so a freshly installed plugin gets the sentence that fixes it instead of a timeout:
+
+```
+copied, but not confirmed: the running app has not loaded demo-panel, so it will not report a reload; restart the app once after installing it
+```
+
 | Flag | Meaning |
 |---|---|
 | `--dest <dir>` | write into this installed copy instead of searching `~/.dsh/profiles/*/node_modules/<name>` |

package/lib/dev.mjs

@@ -61,6 +61,15 @@ export function build({ command, cwd, io = console }) {
 export async function verifyReload({ host, id, timeoutMs = 6000, fetchImpl = fetch, action }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
+  // The app sends its plugin graph first. If this plugin is not in it, no amount
+  // of waiting will produce a rebuilt frame: it was installed after the app
+  // started, and one restart is the fix.
+  let loaded = null;
+  // Two ways to give up — the stream ended, or it timed out — and both mean the
+  // same thing when the app never had this plugin in its graph.
+  const miss = (fallback) => (loaded !== null && loaded.has(id) === false
+    ? `the running app has not loaded ${id}, so it will not report a reload; restart the app once after installing it`
+    : fallback);
   const url = `${String(host).replace(/\/+$/, '')}/plugins/events`;
   try {
     const response = await fetchImpl(url, { headers: { accept: 'text/event-stream' }, signal: controller.signal });
@@ -90,14 +99,19 @@ export async function verifyReload({ host, id, timeoutMs = 6000, fetchImpl = fet
         } catch {
           continue;
         }
+        if (payload.type === 'graph') {
+          const entries = payload.graph?.entries;
+          if (Array.isArray(entries) === true) loaded = new Set(entries.map((entry) => entry.id));
+          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' };
+    return { ok: false, reason: miss('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` };
+    if (error.name === 'AbortError') return { ok: false, reason: miss(`no rebuilt frame for ${id} within ${timeoutMs}ms`) };
     return { ok: false, reason: error.message };
   } finally {
     clearTimeout(timer);

package/lib/testkit/mount.mjs

@@ -177,6 +177,35 @@ export async function mountClient(options) {
       const element = must(selector);
       return Object.fromEntries([...element.attributes].map((attribute) => [attribute.name, attribute.value]));
     },
+    // What a screen reader would report, in the same blunt vocabulary as the
+    // rest: the attributes, not a re-implementation of the accessibility tree.
+    aria: (selector) => {
+      const element = must(selector);
+      const read = (name) => element.getAttribute(name) ?? undefined;
+      return {
+        role: read('role'),
+        label: read('aria-label'),
+        labelledBy: read('aria-labelledby'),
+        describedBy: read('aria-describedby'),
+        live: read('aria-live'),
+        selected: read('aria-selected'),
+        expanded: read('aria-expanded'),
+        checked: read('aria-checked'),
+        pressed: read('aria-pressed'),
+        disabled: read('aria-disabled') ?? (element.disabled === true ? 'true' : undefined),
+        hidden: read('aria-hidden'),
+        text: element.textContent.replace(/\s+/g, ' ').trim(),
+      };
+    },
+    expectAria: (selector, expected) => {
+      const actual = helpers.aria(selector);
+      for (const [key, value] of Object.entries(expected)) {
+        if (actual[key] === value) continue;
+        const shown = actual[key] === undefined ? 'nothing' : `"${actual[key]}"`;
+        throw new Error(`${selector}: expected aria ${key} to be "${value}", but it is ${shown}`);
+      }
+      return actual;
+    },
     snapshot: (dir, name) => {
       const result = compare(dir, name, root.innerHTML);
       if (result.status === 'changed') {

package/package.json

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