dsh-plugin-toolkit 0.20.35 → 0.20.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,66 @@
1
+ ## 0.20.37
2
+
3
+ - **The README tarball gate reads every relative `node <path>` command, not
4
+ only the `scripts/` and `examples/` folders in use today.** A future
5
+ `node ./bin/...`, quoted path, nested folder or `.js`/`.cjs` command is the
6
+ same promise to an installed reader, and previously stepped outside the
7
+ gate. The comparison also judges `package.json`'s `files` list with npm's
8
+ folder, glob and negation semantics instead of exact strings, so a valid
9
+ glob is not reported as a missing command and a trailing `!` entry that
10
+ removes a documented path is not ignored. `test/readme-commands.test.mjs`
11
+ pins the extractor and the files semantics; the 0.20.12 replay still names
12
+ the five paths that release left out.
13
+
14
+ - **The installed preview command runs on Node 18, resolves its peers from the
15
+ package, and the tarball gate now executes it instead of only comparing its
16
+ bytes.** `scripts/preview.mjs` located the package with
17
+ `import.meta.dirname`, which Node added in 20.11; on Node 18 — the oldest
18
+ version `engines.node` promises — the README's
19
+ `node scripts/preview.mjs /tmp/panel.html` threw before it rendered anything.
20
+ It now uses `path.dirname(fileURLToPath(import.meta.url))`, the idiom the
21
+ other shipped scripts already use, and resolves jsdom/React from the package
22
+ first and the caller's project second, so the installed command finds the
23
+ peers where they were installed without borrowing an unrelated checkout's
24
+ `node_modules` by accident.
25
+ `test/preview-tarball.test.mjs` installs the packed tarball into a temp
26
+ prefix, requires every `node <path>` command in the shipped READMEs to exist
27
+ there byte for byte, then runs the installed preview from outside the prefix
28
+ with the optional peers linked and requires exit `0` plus a real HTML page. A
29
+ missing-peer run exits `1` with the install command instead of a stack trace,
30
+ and `test/node18-paths.test.mjs` keeps `import.meta.dirname` and
31
+ `import.meta.filename` out of every shipped source file. The README states
32
+ the optional peers the preview needs.
33
+
34
+ - **The four `node examples/*.mjs` commands run from the installed package, not
35
+ just from a checkout.** The examples mounted `fixtures/...` relative to the
36
+ caller's cwd and `files` omitted those fixtures, so the installed example
37
+ files existed but every command failed with `ENOENT` for the bundle they
38
+ mount. The examples now resolve their bundle and baseline from the package
39
+ root, the two fixture bundles are in `files`, and
40
+ `test/readme-examples-tarball.test.mjs` installs the tarball and runs all
41
+ four from outside the install with the optional peers linked, requiring the
42
+ output the README shows.
43
+
44
+ ## 0.20.36
45
+
46
+ - **`audit --remote` no longer reads an arbitrary `build` script as a pre-pack
47
+ hook.** The remote audit skipped the patch, client and root-export file
48
+ checks whenever `scripts` had a `build` entry, but npm never runs a plain
49
+ `build` script during `npm pack`; only its lifecycle hooks do. A repository
50
+ whose only hook was `scripts.build` therefore passed with no `client.js` in
51
+ the tree even though the tarball contained no bundle either. Build evidence
52
+ now comes only from `prepack` and `prepare` (which run for `npm pack`) and
53
+ `prepublishOnly` (which runs before `npm publish` packs), and an empty hook
54
+ is not evidence. `test/audit-remote-build-hooks.test.mjs` crosses both
55
+ process boundaries: it asks npm what three build-only fixtures actually
56
+ ship, runs the shipped CLI against the same committed tree, and requires exit
57
+ `1` with a failure naming `client.js`; each fixture's `build` script would
58
+ create the client if npm ran it, so the test also proves `npm pack` leaves it
59
+ alone. A `prepack` fixture and a `prepare` fixture that create the file in
60
+ the tarball still exit `0` with the skipped-files note, and a committed
61
+ client beside a `build` script stays clean without the built note. The
62
+ README and `docs/repair.md` state the same rule.
63
+
1
64
  ## 0.20.35
2
65
 
3
66
  - **The compatibility answer now has a reproducible machine-readable form.**
package/README.md CHANGED
@@ -146,7 +146,9 @@ in the right sidebar, for when the conversation is busy.
146
146
  The panel speaks both languages and opens in Chinese; the 中文 / EN switch sits
147
147
  in the dock's header row (and in the sidebar tab) and the choice is remembered.
148
148
 
149
- Look at it without the app:
149
+ Look at it without the app. The preview mounts the panel with the testkit, so it
150
+ needs the optional peers; install them once with
151
+ `npm install --save-dev jsdom react react-dom`:
150
152
 
151
153
  ```sh
152
154
  node scripts/preview.mjs /tmp/panel.html # collapsed, open, with a result, and the tab
@@ -217,7 +219,7 @@ want to assert on it yourself.
217
219
 
218
220
  `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".
219
221
 
220
- Every example below is a file in this repository, run by CI, and the output shown is the output it prints:
222
+ Every example below is shipped in the package, run by CI, and the output shown is the output it prints:
221
223
 
222
224
  | Example | What it shows |
223
225
  | --- | --- |
@@ -435,10 +437,13 @@ What it can see, and what it cannot:
435
437
  declares. A repository whose checkout fails `readme` fails the remote check
436
438
  too, with the same sentence.
437
439
  - File checks (does `exports["./client"]` point at a file that exists, does the
438
- root export `apply`) need the tree. A package that runs `prepack`,
439
- `prepublishOnly`, `prepare` or `build` publishes files it does not commit, so
440
- those checks are **skipped with a note** instead of calling a working plugin
441
- broken.
440
+ root export `apply`) need the tree. npm runs `prepack` and `prepare` before
441
+ `npm pack` creates the tarball, and `prepublishOnly` before `npm publish`
442
+ does, so a package whose lifecycle hook builds those files publishes files it
443
+ does not commit: those checks are **skipped with a note** instead of calling a
444
+ working plugin broken. A plain `build` script is not a lifecycle hook and is
445
+ not evidence by itself, because npm never runs it unless `prepack` or
446
+ `prepare` calls it; put the build there if it produces shipped files.
442
447
  - Public repositories work anonymously, but GitHub allows 60 requests an hour.
443
448
  Export `GH_TOKEN` (or `GITHUB_TOKEN`) to audit more than one or two.
444
449
 
package/examples/aria.mjs CHANGED
@@ -3,9 +3,19 @@
3
3
  *
4
4
  * Run: node examples/aria.mjs
5
5
  */
6
+ import path from 'node:path';
7
+ import { fileURLToPath } from 'node:url';
8
+
6
9
  import { mountClient } from 'dsh-plugin-toolkit/testkit';
7
10
 
8
- const panel = await mountClient({ file: 'fixtures/client-bundle/client.js', copy: { demo: { title: 'Demo' } } });
11
+ // Resolve the bundle from the package, not from the caller's cwd: the same
12
+ // command has to work in a checkout and in an installed package.
13
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
14
+ const panel = await mountClient({
15
+ file: path.join(ROOT, 'fixtures/client-bundle/client.js'),
16
+ resolveFrom: ROOT,
17
+ copy: { demo: { title: 'Demo' } },
18
+ });
9
19
 
10
20
  // expectAria names the attribute that differs, so a failure reads like a bug
11
21
  // report instead of "expected true to equal false".
@@ -4,11 +4,25 @@
4
4
  * Run: node examples/baseline.mjs
5
5
  * First run writes nothing; re-run with UPDATE_SNAPSHOTS=1 to create the file.
6
6
  */
7
+ import path from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+
7
10
  import { expectSnapshot, mountClient } from 'dsh-plugin-toolkit/testkit';
8
11
 
9
- const panel = await mountClient({ file: 'fixtures/client-bundle/client.js', copy: { demo: { title: 'Demo' } } });
12
+ // Resolve the bundle and its baseline from the package, not from the caller's
13
+ // cwd: the same command has to work in a checkout and in an installed package.
14
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
15
+ const panel = await mountClient({
16
+ file: path.join(ROOT, 'fixtures/client-bundle/client.js'),
17
+ resolveFrom: ROOT,
18
+ copy: { demo: { title: 'Demo' } },
19
+ });
10
20
 
11
- const result = expectSnapshot(panel.html(), 'fixtures/client-bundle/__snapshots__', 'panel');
21
+ const result = expectSnapshot(
22
+ panel.html(),
23
+ path.join(ROOT, 'fixtures/client-bundle/__snapshots__'),
24
+ 'panel',
25
+ );
12
26
  console.log(`baseline: ${result.status}`);
13
27
 
14
28
  await panel.unmount();
@@ -4,9 +4,19 @@
4
4
  *
5
5
  * Run: node examples/mount-a-bundle.mjs
6
6
  */
7
+ import path from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+
7
10
  import { mountClient } from 'dsh-plugin-toolkit/testkit';
8
11
 
9
- const panel = await mountClient({ file: 'fixtures/client-bundle/client.js', copy: { demo: { title: 'Demo' } } });
12
+ // Resolve the bundle from the package, not from the caller's cwd: the same
13
+ // command has to work in a checkout and in an installed package.
14
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
15
+ const panel = await mountClient({
16
+ file: path.join(ROOT, 'fixtures/client-bundle/client.js'),
17
+ resolveFrom: ROOT,
18
+ copy: { demo: { title: 'Demo' } },
19
+ });
10
20
 
11
21
  console.log(panel.text());
12
22
 
@@ -4,14 +4,24 @@
4
4
  *
5
5
  * Run: node examples/route-stubs.mjs
6
6
  */
7
+ import path from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+
7
10
  import { createFetch, mountClient } from 'dsh-plugin-toolkit/testkit';
8
11
 
12
+ // Resolve the bundle from the package, not from the caller's cwd: the same
13
+ // command has to work in a checkout and in an installed package.
14
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
9
15
  const stub = createFetch({
10
16
  '/demo/report': { body: { score: 71 } },
11
17
  '/demo/apply': () => ({ status: 201, body: { score: 92 } }),
12
18
  });
13
19
 
14
- const panel = await mountClient({ file: 'fixtures/fetching-bundle/client.js', fetch: stub });
20
+ const panel = await mountClient({
21
+ file: path.join(ROOT, 'fixtures/fetching-bundle/client.js'),
22
+ resolveFrom: ROOT,
23
+ fetch: stub,
24
+ });
15
25
 
16
26
  console.log(panel.text());
17
27
  console.log(`asked for: ${stub.calls('/demo/report').length} route(s), undeclared route answers ${(await stub('/demo/nothing')).status}`);
@@ -0,0 +1,5 @@
1
+ # demo-bundle
2
+
3
+ ## Requirements
4
+
5
+ - DeepSeek Harness `>=0.2.0`
@@ -0,0 +1 @@
1
+ <div class="demo-panel"><h1 class="demo-title">Demo panel</h1><button type="button" aria-label="increment" data-testid="inc">Count 0</button><p class="demo-result" aria-live="polite">0</p></div>
@@ -0,0 +1,31 @@
1
+ window.__ModuleLoader__.load({
2
+ id: 'demo-bundle',
3
+ factory: (require) => {
4
+ const React = require('react');
5
+ const { useState } = React;
6
+ const h = React.createElement;
7
+ const NS = 'demo';
8
+
9
+ function Panel() {
10
+ const [count, setCount] = useState(0);
11
+ return h(
12
+ 'div',
13
+ { className: 'demo-panel' },
14
+ h('h1', { className: 'demo-title' }, 'Demo panel'),
15
+ h(
16
+ 'button',
17
+ { type: 'button', 'aria-label': 'increment', 'data-testid': 'inc', onClick: () => setCount((value) => value + 1) },
18
+ `Count ${count}`,
19
+ ),
20
+ h('p', { className: 'demo-result', 'aria-live': 'polite' }, String(count)),
21
+ );
22
+ }
23
+
24
+ return {
25
+ apply(ctx) {
26
+ ctx.locale.register(NS, { title: 'Demo' });
27
+ ctx.slots.register({ name: 'sidebar.right.pane.tab', key: NS, locale: NS }, Panel);
28
+ },
29
+ };
30
+ },
31
+ });
@@ -0,0 +1 @@
1
+ plugins: []
@@ -0,0 +1,7 @@
1
+ {
2
+ "name": "demo-bundle",
3
+ "version": "1.0.0",
4
+ "engines": { "dsh": ">=0.2.0" },
5
+ "files": ["client.js", "README.md"],
6
+ "dsh": { "bundle": { "patch": "cordis.patch.yml" }, "client": { "platform": "web" } }
7
+ }
@@ -0,0 +1,35 @@
1
+ window.__ModuleLoader__.load({
2
+ id: 'fetching-bundle',
3
+ factory: (require) => {
4
+ const React = require('react');
5
+ const { useEffect, useState } = React;
6
+ const h = React.createElement;
7
+ const NS = 'fetching';
8
+
9
+ function Panel() {
10
+ const [score, setScore] = useState('…');
11
+ useEffect(() => {
12
+ let alive = true;
13
+ fetch('/demo/report')
14
+ .then((response) => response.json())
15
+ .then((body) => {
16
+ if (alive === true) setScore(String(body.score));
17
+ })
18
+ .catch(() => {
19
+ if (alive === true) setScore('failed');
20
+ });
21
+ return () => {
22
+ alive = false;
23
+ };
24
+ }, []);
25
+ return h('div', { className: 'fetching-panel' }, h('p', { 'data-testid': 'score' }, `Score ${score}`));
26
+ }
27
+
28
+ return {
29
+ apply(ctx) {
30
+ ctx.locale.register(NS, { title: 'Fetching' });
31
+ ctx.slots.register({ name: 'sidebar.right.pane.tab', key: NS, locale: NS }, Panel);
32
+ },
33
+ };
34
+ },
35
+ });
package/lib/benchmark.mjs CHANGED
@@ -34,7 +34,7 @@ const MANIFEST = {
34
34
  name: 'benchmark-plugin',
35
35
  version: '1.2.3',
36
36
  main: 'index.js',
37
- scripts: { build: 'node build.mjs' },
37
+ scripts: { prepack: 'node build.mjs' },
38
38
  engines: { dsh: '>=0.2.0' },
39
39
  dsh: { bundle: { patch: 'cordis.patch.yml' }, client: { platform: 'web' } },
40
40
  exports: { '.': './index.js', './client': './client.js' },
@@ -11,14 +11,30 @@
11
11
  import fs from 'node:fs';
12
12
  import path from 'node:path';
13
13
 
14
+ import { isShipped } from './doctor.mjs';
15
+
14
16
  // Both READMEs are in the published file list. A command documented only in
15
17
  // the Chinese README is still a command an installed reader can try to run.
16
18
  export const SHIPPED_READMES = ['README.md', 'README.zh.md'];
17
19
 
18
- // Examples may live below a folder (examples/compatibility-sample/...); keep
19
- // the capture broad enough for a nested path but restricted to the two
20
- // directories the toolkit actually documents as runnable commands.
21
- export const RUN_COMMAND = /\bnode\s+((?:scripts|examples)\/[A-Za-z0-9._/-]+\.mjs)\b/gu;
20
+ // Any relative JavaScript path a reader could run, not only the folders the
21
+ // README happens to use today. A later `node bin/...` or `node ./scripts/...`
22
+ // command must not slip past the gate because its directory or spelling was
23
+ // not on a list. `node --test` and `node -e "..."` are not file commands, and
24
+ // an optional quote keeps a path copied from a fenced or inline block intact.
25
+ export const RUN_COMMAND = /\bnode[ \t]+["'`]?((?:\.\/)?[A-Za-z0-9_@.][A-Za-z0-9._@/-]*\.(?:mjs|cjs|js))["'`]?(?![A-Za-z0-9_])/gu;
26
+
27
+ /** Normalize a captured command to the path npm would store in the tarball. */
28
+ function packageRelative(value) {
29
+ // `path.posix` keeps the comparison platform-independent; npm tarball paths
30
+ // always use forward slashes and never a leading `./`.
31
+ const normalized = path.posix.normalize(value).replace(/^(?:\.\/)+/u, '');
32
+ // A path outside the package root is not a claim about the tarball.
33
+ if (normalized === '' || normalized === '.' || normalized.startsWith('../') || normalized.startsWith('/')) {
34
+ return null;
35
+ }
36
+ return normalized;
37
+ }
22
38
 
23
39
  /** Every distinct runnable path the shipped READMEs tell a reader to pass to node. */
24
40
  export function documentedRunCommands(root, readmes = SHIPPED_READMES) {
@@ -30,14 +46,21 @@ export function documentedRunCommands(root, readmes = SHIPPED_READMES) {
30
46
  // normalize before matching the line a reader copies.
31
47
  const text = fs.readFileSync(file, 'utf8').replace(/\r\n/gu, '\n');
32
48
  for (const match of text.matchAll(RUN_COMMAND)) {
33
- if (found.has(match[1]) === false) found.set(match[1], readme);
49
+ const command = packageRelative(match[1]);
50
+ if (command !== null && found.has(command) === false) found.set(command, readme);
34
51
  }
35
52
  }
36
53
  return found;
37
54
  }
38
55
 
39
- /** Documented paths that the given shipped-file list does not contain. */
56
+ /**
57
+ * Documented paths that the given shipped-file list does not contain.
58
+ *
59
+ * Both `npm pack --dry-run --json` output and `package.json`'s `files` list
60
+ * are accepted. The latter may use npm's folder, glob and negation entries, so
61
+ * judging it as a set of exact strings would report a path missing even when
62
+ * npm packs it (and miss a negated entry that drops it).
63
+ */
40
64
  export function missingRunCommands(documented, shipped) {
41
- const files = new Set(shipped);
42
- return [...documented.keys()].filter((command) => files.has(command) === false).sort();
65
+ return [...documented.keys()].filter((command) => isShipped(command, shipped) === false).sort();
43
66
  }
package/lib/remote.mjs CHANGED
@@ -400,8 +400,17 @@ export async function auditRemote(
400
400
  // tarball will contain: `lib/` is output, not source. Asking GitHub whether
401
401
  // those paths exist would call a working plugin broken, so the file-level
402
402
  // checks are reported as skipped instead of failed.
403
- const BUILD_HOOKS = ['prepack', 'prepublishOnly', 'prepare', 'build'];
404
- const builds = BUILD_HOOKS.filter((hook) => typeof manifest.scripts?.[hook] === 'string');
403
+ //
404
+ // Only npm's own lifecycle hooks are evidence. `prepack` and `prepare` run
405
+ // during `npm pack`, and `prepublishOnly` runs before `npm publish` creates
406
+ // its tarball. A plain `build` script is not a lifecycle hook: npm never runs
407
+ // it unless one of those hooks (or a person) calls it, so a repository whose
408
+ // only script is `scripts.build` ships exactly what is committed.
409
+ const BUILD_HOOKS = ['prepack', 'prepublishOnly', 'prepare'];
410
+ const builds = BUILD_HOOKS.filter((hook) => {
411
+ const script = manifest.scripts?.[hook];
412
+ return typeof script === 'string' && script.trim() !== '';
413
+ });
405
414
  const built = builds.length > 0;
406
415
 
407
416
  // `engines.dsh` deserves the wording the installer actually uses: a host that
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.35",
3
+ "version": "0.20.37",
4
4
  "description": "Preflight, release and test DeepSeek Harness plugins: check a folder or any GitHub repository, wait for npm to actually serve the version, and keep the market index honest.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -31,6 +31,8 @@
31
31
  "examples/compatibility-sample/",
32
32
  "examples/mount-a-bundle.mjs",
33
33
  "examples/route-stubs.mjs",
34
+ "fixtures/client-bundle/",
35
+ "fixtures/fetching-bundle/",
34
36
  "scripts/benchmark-audit.mjs",
35
37
  "scripts/compatibility-sample.mjs",
36
38
  "scripts/preview.mjs"
@@ -8,11 +8,38 @@
8
8
  */
9
9
  import fs from 'node:fs';
10
10
  import path from 'node:path';
11
+ import { fileURLToPath } from 'node:url';
12
+
13
+ import { requireFrom } from '../lib/testkit/env.mjs';
11
14
  import { createHost, createFetch, mountClient } from '../lib/testkit/index.mjs';
12
15
 
13
- const ROOT = path.resolve(import.meta.dirname, '..');
16
+ // `import.meta.dirname` is Node 20.11+, and this package supports Node 18.
17
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
14
18
  const out = process.argv[2] ?? '/tmp/kit-preview.html';
15
19
 
20
+ // Mounting needs the optional testkit peers. Look in the package first (an
21
+ // installed preview should use the peers installed next to it), then in the
22
+ // caller's project (the way testkit itself resolves a plugin's dependencies).
23
+ // Those are the two places a real install puts them; do not walk arbitrary
24
+ // ancestors. Name the install command instead of letting a missing package
25
+ // surface as a stack trace from the first mount.
26
+ const PEERS = ['jsdom', 'react', 'react-dom/client'];
27
+ let peerRoot = null;
28
+ for (const anchor of [ROOT, process.cwd()]) {
29
+ try {
30
+ for (const name of PEERS) requireFrom(name, anchor);
31
+ peerRoot = anchor;
32
+ break;
33
+ } catch {
34
+ // Try the next place the peers could legitimately live.
35
+ }
36
+ }
37
+ if (peerRoot === null) {
38
+ console.error('preview: the testkit needs the optional peers jsdom, react and react-dom to mount the panel.');
39
+ console.error('preview: install them in the project you run this from: npm install --save-dev jsdom react react-dom');
40
+ process.exit(1);
41
+ }
42
+
16
43
  const result = {
17
44
  ok: false,
18
45
  dir: '/Users/you/work/my-plugin',
@@ -59,6 +86,9 @@ let firstPanel = null; // the injected stylesheet, read while the first panel is
59
86
  for (const state of states) {
60
87
  const panel = await mountClient({
61
88
  file: path.join(ROOT, 'client.js'),
89
+ // Use the same React and jsdom the peer check found: the package's own
90
+ // install root when it has them, the caller's project otherwise.
91
+ resolveFrom: peerRoot,
62
92
  slot: state.slot,
63
93
  host: createHost({ locale: { en: {}, zh: {} } }),
64
94
  fetch: createFetch({ '/toolkit/check': { body: state.route === 'search' ? CANDIDATES : state.route === 'repo' ? REPO_RESULT : result } }),