dsh-plugin-toolkit 0.4.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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.
+
+- Writes eight files: `package.json` (with `engines.dsh`, the patch file and a `files` list that actually ships the code), `cordis.patch.yml`, `index.js`, `client.js` (a sidebar tab), a testkit test for that tab, a CI workflow that runs both, `README.md` and `.gitignore`.
+- Refuses a directory that is not empty unless `--force`, and refuses a name npm would refuse — the two mistakes that cost the most time later.
+- The template is embedded, so `init` works offline.
+
 ## 0.4.1
 
 - `examples/`: four runnable files (`mount-a-bundle`, `route-stubs`, `baseline`, `aria`), each showing one thing testkit does.

package/README.md

@@ -25,6 +25,25 @@ Releasing one plugin fifteen times taught me three things the ecosystem's toolin
 3. **Reading a manifest is not the same as checking it.** A plugin can have a valid `package.json` and still be uninstallable: `files` that omit the entry the manifest points at, a bundle patch that does not exist, a README that never states the host range it declares.
 
 
+## Start from a plugin that already passes
+
+```sh
+$ npx dsh-plugin-toolkit@0.5.0 init ./my-panel --name my-panel --title "My panel"
+created 8 file(s) in /Users/you/my-panel
+  .github/workflows/ci.yml
+  .gitignore
+  README.md
+  client.js
+  cordis.patch.yml
+  index.js
+  package.json
+  test/panel.test.mjs
+
+next: npm install && npm test && npm run doctor
+```
+
+What you get is not a snippet: it is a plugin whose `doctor` already passes (`engines.dsh`, the patch file, the `files` list), with a client bundle that registers a sidebar tab, a testkit test for it, and a CI workflow that runs both. `init` refuses a directory that is not empty unless you pass `--force`, and refuses a name npm would refuse — those are the two mistakes that cost the most time later.
+
 ## Test a panel without a browser
 
 A plugin's client code is one file that calls `window.__ModuleLoader__.load({factory})` — there is no module to import, so the usual React test setup does not apply. `testkit` supplies the missing half: a DOM, the real React, and a host context that records what the panel registers.
@@ -179,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

@@ -6,6 +6,8 @@
 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';
 
@@ -16,6 +18,8 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
   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
+  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
@@ -25,6 +29,9 @@ Flags
   --pr                      commit the index on a branch, push it, open the pull request
   --merge                   with --pr: wait for checks, then squash-merge
   --base <branch>           base branch for the pull request, default main
+  --name <package-name>     with init: the npm name, required
+  --title <text>            with init: the tab title, default "My panel"
+  --force                   with init: write into a directory that is not empty
 `;
 
 function flags(argv) {
@@ -38,6 +45,10 @@ 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 === '--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];
@@ -81,6 +92,35 @@ 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');
+      return 2;
+    }
+    const result = init({ dir, name: options.name, title: options.title, force: options.force === true });
+    if (result.ok !== true) {
+      io.error(`dsh-plugin init: ${result.failures[0].message}`);
+      return 1;
+    }
+    io.log(`created ${result.files.length} file(s) in ${result.dir}`);
+    for (const file of result.files) io.log(`  ${file}`);
+    io.log('');
+    io.log('next: npm install && npm test && npm run doctor');
+    return 0;
+  }
+
   if (command === 'index') {
     const target = options.index ?? (dir.endsWith('.json') === true ? dir : path.join(dir, 'market/index.json'));
     const index = readIndex(target);

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/init.mjs

@@ -0,0 +1,171 @@
+/**
+ * Scaffolding, so the first ten minutes are not spent discovering that the
+ * market index rejects a plugin without `engines.dsh`.
+ *
+ * The template is embedded, not fetched: `init` has to work on a plane.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+export function checkName(name) {
+  if (typeof name !== 'string' || NPM_NAME.test(name) === false) {
+    return 'name must be a valid npm package name, e.g. my-plugin or @me/my-plugin';
+  }
+  return null;
+}
+
+function manifest({ name, title, version }) {
+  return `${JSON.stringify(
+    {
+      name,
+      version,
+      description: `${title} — a panel for DeepSeek Harness`,
+      license: 'MIT',
+      type: 'module',
+      engines: { node: '>=18', dsh: '>=0.2.0' },
+      main: 'index.js',
+      files: ['index.js', 'client.js', 'cordis.patch.yml', 'README.md'],
+      scripts: { test: 'node --test', doctor: 'dsh-plugin doctor .' },
+      devDependencies: {
+        'dsh-plugin-toolkit': '^0.5.0',
+        jsdom: '^26.1.0',
+        react: '^18.3.1',
+        'react-dom': '^18.3.1',
+      },
+      dsh: {
+        bundle: { patch: './cordis.patch.yml' },
+        client: {
+          platform: 'web',
+          immediately: true,
+          inject: ['@deepseek-ai/dsh-client-ui-conversation'],
+        },
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function client({ name, title }) {
+  return `window.__ModuleLoader__.load({
+  id: '${name}',
+  factory: (require) => {
+    const React = require('react');
+    const { useState } = React;
+    const h = React.createElement;
+    const NS = '${name}';
+    const KIND = '${name}';
+
+    const COPY = {
+      en: { tabTitle: '${title}', title: '${title}', body: 'This panel came from dsh-plugin init.', clicks: 'Clicks' },
+    };
+
+    function Panel() {
+      const [clicks, setClicks] = useState(0);
+      return h(
+        'div',
+        { className: 'panel' },
+        h('h1', { className: 'panel-title' }, COPY.en.title),
+        h('p', { className: 'panel-body' }, COPY.en.body),
+        h(
+          'button',
+          { type: 'button', className: 'panel-button', onClick: () => setClicks((value) => value + 1) },
+          \`\${COPY.en.clicks}: \${clicks}\`,
+        ),
+      );
+    }
+
+    return {
+      apply(ctx) {
+        ctx.locale.register(NS, COPY);
+        const dispose = ctx.inject(['sidebarRightTabs', 'sidebarRight'], (tabCtx) => {
+          if (tabCtx.slots === undefined) return;
+          const tr = tabCtx.locale.bind(NS);
+          const offType = tabCtx.sidebarRightTabs.register({
+            id: NS,
+            kind: KIND,
+            title: () => tr('tabTitle'),
+            guide: [{ id: 'panel', order: 40, title: () => tr('title'), description: () => tr('body') }],
+          });
+          const offBody = tabCtx.slots.register({ name: 'sidebar.right.pane.tab', key: NS, locale: NS }, Panel);
+          return () => {
+            offBody?.();
+            offType?.();
+          };
+        });
+        return () => dispose?.();
+      },
+    };
+  },
+});
+`;
+}
+
+function test({ name, title }) {
+  return `import assert from 'node:assert/strict';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { mountClient } from 'dsh-plugin-toolkit/testkit';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+test('the panel renders and its button counts', async () => {
+  const panel = await mountClient({
+    file: path.join(here, '..', 'client.js'),
+    copy: { '${name}': { tabTitle: '${title}', title: '${title}', body: 'This panel came from dsh-plugin init.', clicks: 'Clicks' } },
+  });
+  assert.match(panel.text(), /${title}/);
+  await panel.click('button');
+  assert.match(panel.text(), /Clicks: 1/);
+  await panel.unmount();
+});
+`;
+}
+
+export function files({ name, title = 'My panel', version = '0.1.0' }) {
+  const slug = name.includes('/') ? name.split('/')[1] : name;
+  return {
+    'package.json': manifest({ name, title, version }),
+    'cordis.patch.yml': `- insert:\n    - id: ${name}\n      name: '${name}'\n      config: {}\n`,
+    'index.js': `export const name = '${name}';\n\n// The host half runs in Node. Most panels need nothing here.\nexport function apply() {}\n`,
+    'client.js': client({ name, title }),
+    'test/panel.test.mjs': test({ name, title }),
+    'README.md': `# ${slug}\n\n${title} — a panel for DeepSeek Harness.\n\n## Requirements\n\n| What | Version | Why |\n| --- | --- | --- |\n| DeepSeek Harness | >= 0.2.0 | provides \`sidebarRightTabs\` |\n| Node | >= 18 | the host half |\n\n## Develop\n\n\`\`\`sh\nnpm install\nnpm test            # mounts client.js in Node\nnpm run doctor      # checks the manifest before you publish\n\`\`\`\n\n## Install\n\n\`\`\`sh\ndsh plugin add ${name}\n\`\`\`\n`,
+    '.gitignore': 'node_modules/\n',
+    '.github/workflows/ci.yml': `name: ci\n\non:\n  push:\n    branches: [main]\n  pull_request:\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node: [18, 20, 22]\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \${{ matrix.node }}\n      - run: npm install\n      - run: npm test\n      - run: npx --yes dsh-plugin-toolkit@0.5.0 doctor .\n`,
+  };
+}
+
+export function init({ dir, name, title, force = false }) {
+  const problem = checkName(name);
+  if (problem !== null) return { ok: false, failures: [{ check: 'name', message: problem }] };
+
+  const target = path.resolve(dir);
+  if (fs.existsSync(target) === true) {
+    const entries = fs.readdirSync(target).filter((entry) => entry !== '.git');
+    if (entries.length > 0 && force !== true) {
+      return {
+        ok: false,
+        failures: [
+          {
+            check: 'dir',
+            message: `${target} is not empty (${entries.slice(0, 3).join(', ')}); pass --force to write into it anyway`,
+          },
+        ],
+      };
+    }
+  }
+
+  const written = [];
+  for (const [relative, content] of Object.entries(files({ name, title }))) {
+    const file = path.join(target, relative);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    written.push(relative);
+  }
+  return { ok: true, dir: target, files: written.sort() };
+}

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.4.1",
+  "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": {