dsh-plugin-toolkit 0.5.0 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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

@@ -198,6 +198,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.6.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.6.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:

package/lib/cli.mjs

@@ -7,6 +7,7 @@ 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';
 
@@ -18,6 +19,7 @@ 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 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 verify [dir]           pack it, install the tarball, mount the installed panel
 
 Flags
   --dry-run                 show the steps without touching anything
@@ -46,6 +48,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 +92,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.6.3",
   "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": {