dsh-plugin-toolkit 0.8.7 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.9.0
+
+- `audit`: every plugin installed in a profile, in one pass — version, whether the
+  installed copy passes the same checks `doctor` runs, and whether the running app
+  loaded it (read from the graph frame on `/plugins/events`). Answers "why is my
+  plugin not in the sidebar?" with the plugin named.
+- `doctor --installed` (used by `audit`): skip the `files` check. After install the
+  tarball is already unpacked, so `files` cannot decide what shipped — npm always
+  ships `package.json` and the README, and the check reported false problems for
+  every published plugin.
+- `client entry` accepts the bundle named by the `./client` export, which is how a
+  package with a `dsh/` folder names its bundle (`@liustack/modlens` was reported
+  as missing its own client bundle).
+
+## 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

package/README.md

@@ -15,7 +15,7 @@ npx dsh-plugin-toolkit@0.7.0 release --pr --merge              # tag, wait for n
 | 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 |
+| changing a panel that is already installed | [`dev`](#2-develop-a-panel) | `mount`, the testkit, `audit` |
 | shipping a version | [`verify`](#3-ship-a-version) | `release`, `index` |
 
 It also installs as a plugin. `dsh plugin add dsh-plugin-toolkit` adds a
@@ -196,6 +196,26 @@ AIignore No workspace yet Could not read the report …
 dsh plugin add dsh-plugin-example
 ```
 
+## See what is installed, and what the app loaded
+
+`doctor` checks one folder you name. The question that actually gets asked is
+"why is my plugin not in the sidebar?", and the answer needs three things at once:
+what is installed, whether each installed copy is valid, and which of them the
+running app actually loaded.
+
+```sh
+$ dsh-plugin audit --host http://127.0.0.1:54133
+dsh-aiignore           0.37.1    loaded       ok
+demo-panel             0.3.0     not loaded   1 problem: root export
+                                                    root export: the root export index.js does not export apply, so the loader imports the package and mounts nothing
+
+1 installed plugin(s) are not in the running app; restart the app once after installing.
+```
+
+Without `--host` the loaded column is `?`, because guessing would be worse than
+saying nothing. Only packages that declare a `dsh` field are audited — the rest of
+`node_modules` is ordinary dependencies, and auditing those is noise.
+
 ## 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.
@@ -217,6 +237,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/audit.mjs

@@ -0,0 +1,98 @@
+/**
+ * Every plugin installed in a profile, checked in one pass.
+ *
+ * `doctor` answers "is this plugin correct?" for one folder you name. The
+ * question that actually gets asked is "why is my plugin not in the sidebar?",
+ * and the answer depends on three things a single folder cannot tell you: what
+ * is installed, whether each installed copy is valid, and which of them the
+ * running app actually loaded.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { doctor } from './doctor.mjs';
+import { readGraph } from './dev.mjs';
+
+/** Every package folder inside every profile, scoped names included. */
+export function listInstalled({ home = path.join(os.homedir(), '.dsh') } = {}) {
+  const profiles = path.join(home, 'profiles');
+  if (fs.existsSync(profiles) === false) return [];
+  const found = [];
+  for (const profile of fs.readdirSync(profiles).sort()) {
+    const modules = path.join(profiles, profile, 'node_modules');
+    if (fs.existsSync(modules) === false) continue;
+    for (const entry of fs.readdirSync(modules).sort()) {
+      if (entry.startsWith('.') === true) continue;
+      const candidates = entry.startsWith('@')
+        ? fs.readdirSync(path.join(modules, entry)).sort().map((name) => path.join(modules, entry, name))
+        : [path.join(modules, entry)];
+      for (const dir of candidates) {
+        const manifestPath = path.join(dir, 'package.json');
+        if (fs.existsSync(manifestPath) === false) continue;
+        let manifest;
+        try {
+          manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        } catch {
+          // A package.json that does not parse is still an installed plugin, and
+          // "it does not parse" is exactly what the author needs to hear.
+          manifest = { name: path.basename(dir) };
+        }
+        // Only packages that declare themselves as plugins. node_modules is full
+        // of ordinary dependencies, and auditing those is noise.
+        if (manifest.dsh === undefined) continue;
+        found.push({ dir, manifest, profile });
+      }
+    }
+  }
+  return found;
+}
+
+function describe({ failures }) {
+  if (failures.length === 0) return 'ok';
+  return `${failures.length} problem${failures.length === 1 ? '' : 's'}: ${failures[0].check}`;
+}
+
+export async function audit({ home, host, io = console, fetchImpl, timeoutMs = 3000 } = {}) {
+  const installed = listInstalled({ home });
+  if (installed.length === 0) {
+    io.log('no plugins installed in any profile (a plugin declares a "dsh" field)');
+    return { ok: true, plugins: [], graph: null };
+  }
+
+  let graph = null;
+  if (typeof host === 'string' && host.length > 0) {
+    graph = await readGraph({ host, timeoutMs, fetchImpl });
+    if (graph.ok !== true) io.log(`could not read the plugin graph: ${graph.reason}`);
+  }
+
+  const rows = installed.map(({ dir, manifest, profile }) => {
+    let failures;
+    try {
+      ({ failures } = doctor(dir, { installed: true }));
+    } catch (error) {
+      failures = [{ check: 'manifest', message: error.message }];
+    }
+    const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
+    return { name: manifest.name, version: manifest.version ?? '?', profile, dir, failures, loaded };
+  });
+
+  const width = Math.max(...rows.map((row) => row.name.length), 6);
+  for (const row of rows) {
+    const state = row.loaded === null ? '?' : row.loaded === true ? 'loaded' : 'not loaded';
+    io.log(`${row.name.padEnd(width)}  ${String(row.version).padEnd(8)}  ${state.padEnd(10)}  ${describe(row)}`);
+    for (const failure of row.failures) io.log(`${' '.repeat(width + 22)}${failure.check}: ${failure.message}`);
+  }
+
+  const failed = rows.filter((row) => row.failures.length > 0);
+  const notLoaded = rows.filter((row) => row.loaded === false);
+  if (notLoaded.length > 0) {
+    io.log('');
+    io.log(`${notLoaded.length} installed plugin(s) are not in the running app; restart the app once after installing.`);
+  }
+  if (failed.length > 0) {
+    io.log('');
+    io.log(`${failed.length} of ${rows.length} installed plugin(s) have problems.`);
+  }
+  return { ok: failed.length === 0, plugins: rows, graph };
+}

package/lib/cli.mjs

@@ -25,6 +25,8 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
   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 audit [flags]              every installed plugin: valid, and loaded by the running app
+      dsh-plugin audit --host http://127.0.0.1:54133
   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
 
@@ -74,6 +76,7 @@ function flags(argv) {
     else if (token === '--pr') parsed.pr = true;
     else if (token === '--merge') parsed.merge = true;
     else if (token === '--publish') parsed.publish = true;
+    else if (token === '--home') { parsed.home = args[++index]; }
     else if (token === '--base') parsed.base = argv[++index];
     else if (token === '--market') parsed.market = argv[++index];
     else if (token.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
@@ -158,6 +161,12 @@ export async function run(argv, io = console) {
     return problems === 0 ? 0 : 1;
   }
 
+  if (command === 'audit') {
+    const { audit } = await import('./audit.mjs');
+    const result = await audit({ home: options.home, host: options.host, timeoutMs: options.timeout, io });
+    return result.ok === true ? 0 : 1;
+  }
+
   if (command === 'dev') {
     const { dev } = await import('./dev.mjs');
     return dev({

package/lib/dev.mjs

@@ -16,7 +16,9 @@ const IGNORED = new Set(['node_modules', '.git', 'docs', 'test', 'tests', 'cover
 
 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');
+  const exported = manifest?.exports;
+  const subpath = typeof exported === 'string' ? undefined : exported?.['./client'];
+  const candidates = [declared, subpath, '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;
@@ -61,6 +63,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 +101,62 @@ 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: miss(`no rebuilt frame for ${id} within ${timeoutMs}ms`) };
+    return { ok: false, reason: error.message };
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+/**
+ * The app's own list of what it loaded, read once. `audit` uses it to answer
+ * "installed, but why is there no panel?" for every plugin at once.
+ */
+export async function readGraph({ host, timeoutMs = 3000, fetchImpl = fetch }) {
+  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 = '';
+    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;
+        let payload;
+        try {
+          payload = JSON.parse(data.slice(6));
+        } catch {
+          continue;
+        }
+        if (payload.type !== 'graph' || Array.isArray(payload.graph?.entries) === false) continue;
+        return { ok: true, ids: new Set(payload.graph.entries.map((entry) => entry.id)) };
+      }
+    }
+    return { ok: false, reason: 'the stream ended before a graph 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: `no graph frame within ${timeoutMs}ms` };
     return { ok: false, reason: error.message };
   } finally {
     clearTimeout(timer);

package/lib/doctor.mjs

@@ -87,7 +87,14 @@ export function checkPatchFile(dir, manifest) {
 export function checkClientEntry(dir, manifest) {
   const client = manifest.dsh?.client;
   if (client === undefined || client === null) return null;
-  const entries = ['client.js', 'lib/client.js', 'dist/client.js'];
+  // The declared entry comes first, then the `./client` export (how a package
+  // with a `dsh/` folder names its bundle), then the plain file names. A plugin
+  // that ships `dsh/client.js` is not wrong for failing to also ship `client.js`.
+  const exported = manifest.exports;
+  const subpath = typeof exported === 'string' ? undefined : exported?.['./client'];
+  const entries = [client.entry, subpath, 'client.js', 'lib/client.js', 'dist/client.js']
+    .filter((entry) => typeof entry === 'string' && entry.length > 0)
+    .map((entry) => entry.replace(/^\.\//u, ''));
   const found = entries.some((entry) => fs.existsSync(path.join(dir, entry)));
   return found ? null : `dsh.client is declared but none of ${entries.join(', ')} exists`;
 }
@@ -173,7 +180,7 @@ export function checkRootExport(dir, manifest) {
 }
 
 /** Runs every check and returns `{ failures, notes }`. */
-export function doctor(dir) {
+export function doctor(dir, { installed = false } = {}) {
   const { manifest } = readManifest(dir);
   const checks = [
     ['version', checkVersion(manifest)],
@@ -182,7 +189,9 @@ export function doctor(dir) {
     ['dsh field', checkDshField(manifest)],
     ['patch file', checkPatchFile(dir, manifest)],
     ['client entry', checkClientEntry(dir, manifest)],
-    ['files list', checkFilesList(manifest)],
+    // After install the tarball is already unpacked, so `files` cannot be used to
+    // decide what shipped: npm always ships package.json and the README.
+    ['files list', installed === true ? null : checkFilesList(manifest)],
     ['root export', checkRootExport(dir, manifest)],
   ];
   const failures = checks.filter(([, result]) => result !== null && typeof result === 'string');

package/package.json

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