dsh-plugin-toolkit 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.8.4
+
+- README: `## When the panel does not appear` — the five checks that explain a
+  successful install with nothing on screen (restart, root export, tarball,
+  patch row, a bundle that throws). Each one is a failure this tool has already
+  hit. A test keeps the section from losing a step.
+- `doctor` table lists the new `root export` check; the verify example no longer
+  pins an old version in its own docs.
+
+## 0.8.3
+
+`verify` now imports the host half it just installed.
+
+- After installing the tarball, `verify` imports the module the loader will
+  import (`exports["."]`, else `main`) and requires an `apply` function. A root
+  module that throws on import — which `doctor`'s static read cannot see — is
+  now a failure: `the installed index.js does not import: boom`.
+- `--no-mount` skips the DOM, not the install, so the host half is checked in
+  both modes. The success line says which half ran.
+
 ## 0.8.2
 
 `doctor` now refuses the failure that shipped in 0.8.0.

package/README.md

@@ -247,6 +247,7 @@ latest release.
 | `patch file` | The path declared above must be a real file |
 | `client entry` | If `dsh.client` is declared, the bundle has to be there |
 | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` |
+| `root export` | The loader imports the bare package name; if that module is the CLI (or exports no `apply`), the row mounts nothing while the install reports success |
 
 Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged.
 
@@ -255,7 +256,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.7.0 verify .
+$ npx dsh-plugin-toolkit verify .
 ok  packed 5 file(s), installed the tarball, mounted the panel
     My panel This panel came from dsh-plugin init. Clicks: 0
 ```
@@ -263,11 +264,37 @@ 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.7.0 verify .
+$ npx dsh-plugin-toolkit verify .
 dsh-plugin verify: stopped at pack
   ✗ pack: the tarball does not contain client.js, so the installed plugin has no panel
 ```
 
+## When the panel does not appear
+
+The install reports success and nothing shows up. In this order:
+
+1. **Did the host restart?** Client bundles are read at startup. `dsh plugin add`
+   writes the profile; the running window still has the old bundle.
+2. **Is the root export the plugin?**
+   ```sh
+   node -e "import('my-plugin').then((m) => console.log(typeof m.apply))"
+   ```
+   `function` is what the loader needs. `undefined` means `exports["."]` points
+   at the CLI — `0.8.0` of this tool shipped exactly that.
+3. **Does the tarball ship the panel?** `dsh-plugin verify .` installs what users
+   get and mounts it. `doctor` cannot see this.
+4. **Is the patch row shaped right?** `cordis.patch.yml` needs one `- insert:`
+   entry with `id` and `name`:
+   ```yaml
+   - insert:
+       - id: my-plugin
+         name: my-plugin
+         config: {}
+   ```
+5. **Did the client bundle throw?** The host logs the loader error with the
+   plugin id; a bundle that throws at factory time looks identical to one that
+   never loaded.
+
 ## What `release` does
 
 `release` runs the sequence in the order that fails cheapest first:

package/lib/cli.mjs

@@ -108,7 +108,8 @@ export async function run(argv, io = console) {
   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`);
+      const what = result.stage === 'mount' ? 'installed the tarball, mounted the panel' : 'installed the tarball and imported its host half';
+      io.log(`ok  packed ${result.files.length} file(s), ${what}`);
       if (typeof result.text === 'string') io.log(`    ${result.text}`);
       return 0;
     }

package/lib/doctor.mjs

@@ -143,14 +143,20 @@ export function checkFilesList(manifest) {
  * ships both a CLI and a panel is one `exports` edit away from having its root
  * point at the CLI — the row then mounts nothing, and pnpm reports success.
  */
-export function checkRootExport(dir, manifest) {
-  if (manifest.dsh === undefined || manifest.dsh === null) return null;
+/** The module the loader imports when it starts the bare package name. */
+export function rootEntry(manifest) {
   const root = typeof manifest.exports === 'object' && manifest.exports !== null ? manifest.exports['.'] : undefined;
   const entry = typeof root === 'string' ? root : manifest.main;
-  // A bundle that inserts a subpath plugin needs no root module at all.
   if (typeof entry !== 'string') return null;
+  return entry.replace(/^\.\//, '');
+}
 
-  const target = entry.replace(/^\.\//, '');
+export function checkRootExport(dir, manifest) {
+  if (manifest.dsh === undefined || manifest.dsh === null) return null;
+  const target = rootEntry(manifest);
+  // A bundle that inserts a subpath plugin needs no root module at all.
+  if (target === null) return null;
+  const entry = target;
   const bins = Object.values(manifest.bin ?? {}).filter((value) => typeof value === 'string');
   if (bins.some((bin) => bin.replace(/^\.\//, '') === target) === true) {
     return `exports["."] points at the CLI (${entry}), so the loader's row has no plugin to apply; point it at the module that exports apply`;

package/lib/verify.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 
 import { doctor, declaredPaths } from './doctor.mjs';
 import { resolveEntry } from './dev.mjs';
+import { rootEntry } from './doctor.mjs';
 import { run } from './exec.mjs';
 
 function packJson(dir) {
@@ -78,7 +79,6 @@ export async function verify({ dir, mount = true }) {
 
   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;
@@ -108,6 +108,46 @@ export async function verify({ dir, mount = true }) {
     };
   }
 
+  // The loader starts the host half by importing the bare package name. Doing
+  // the same import here is the only way to know the row will have an apply —
+  // 0.8.0 shipped a package whose root export was the CLI, installed cleanly,
+  // and mounted nothing.
+  const rootFile = rootEntry(report.manifest);
+  if (rootFile !== null) {
+    const absolute = path.join(installed, rootFile);
+    if (fs.existsSync(absolute) === false) {
+      return {
+        ok: false,
+        stage: 'install',
+        failures: [{ check: 'root export', message: `the tarball does not ship ${rootFile}, which package.json points the loader at` }],
+        files: packed.files,
+      };
+    }
+    try {
+      const { pathToFileURL } = await import('node:url');
+      const loaded = await import(pathToFileURL(absolute).href);
+      if (typeof loaded.apply !== 'function') {
+        return {
+          ok: false,
+          stage: 'install',
+          failures: [{ check: 'root export', message: `the installed ${rootFile} exports no apply, so the loader's row mounts nothing` }],
+          files: packed.files,
+        };
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        stage: 'install',
+        failures: [{ check: 'root export', message: `the installed ${rootFile} does not import: ${error.message}` }],
+        files: packed.files,
+      };
+    }
+  }
+
+  // `--no-mount` skips the DOM, not the install: the host half is the half
+  // that silently fails, and importing it needs nothing but Node.
+  if (mount === false) return { ok: true, stage: 'pack', failures: [], files: packed.files, size: packed.size };
+
   // Same convention the host uses: dsh.client.entry, then client.js.
   const entryFile = resolveEntry(installed, report.manifest);
   if (entryFile !== null) {

package/package.json

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