dsh-plugin-toolkit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- `test/examples.test.mjs` runs every example and asserts it prints exactly what the README shows, and that the README names each one. An example that does not run teaches a shape that no longer exists.
+- `fixtures/fetching-bundle/`: a bundle that calls its host on mount, so the route-stub example asserts something real instead of printing zeros.
+
 ## 0.4.0
 
 `release` can now finish the job instead of printing the next command.

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.
@@ -78,6 +97,27 @@ assert.match(panel.must('[role="status"]').textContent, /Score moved 71 → 77/)
 
 `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:
+
+| Example | What it shows |
+| --- | --- |
+| `node examples/mount-a-bundle.mjs` | mount a real bundle, read the text, click, read it again |
+| `node examples/route-stubs.mjs` | answer the routes a panel asks for, and assert on the requests |
+| `node examples/baseline.mjs` | a DOM baseline compared on every run |
+| `node examples/aria.mjs` | what assistive tech sees |
+
+```sh
+$ node examples/mount-a-bundle.mjs
+Demo panel Count 0 0
+Demo panel Count 1 1
+```
+
+```sh
+$ node examples/route-stubs.mjs
+Score 71
+asked for: 1 route(s), undeclared route answers 404
+```
+
 To look at a bundle by hand:
 
 ```sh

package/lib/cli.mjs

@@ -6,6 +6,7 @@
 import path from 'node:path';
 
 import { doctor } from './doctor.mjs';
+import { init } from './init.mjs';
 import { plan, release } from './release.mjs';
 import { auditVersions, readIndex } from './index-file.mjs';
 
@@ -16,6 +17,7 @@ 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
 
 Flags
   --dry-run                 show the steps without touching anything
@@ -25,6 +27,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 +43,9 @@ 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 === '--dest') parsed.dest = argv[++index];
     else if (token === '--entry') parsed.entry = argv[++index];
     else if (token === '--build') parsed.build = argv[++index];
@@ -81,6 +89,23 @@ export async function run(argv, io = console) {
     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/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/package.json

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