dsh-plugin-toolkit 0.20.36 → 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,46 @@
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
+
1
44
  ## 0.20.36
2
45
 
3
46
  - **`audit --remote` no longer reads an arbitrary `build` script as a pre-pack
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
  | --- | --- |
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
+ });
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.36",
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 } }),