dsh-plugin-toolkit 0.20.8 → 0.20.10

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,32 @@
1
+ ## 0.20.10
2
+
3
+ - **`expectSnapshot()` writes the baseline when `UPDATE_SNAPSHOTS=1`.** The
4
+ documented rerun now writes the normalised HTML and returns
5
+ `{ status: "written" }` instead of failing with the same missing-baseline
6
+ error. Without the variable, a missing or changed baseline still fails, so a
7
+ snapshot is never written as a side effect of an ordinary test run.
8
+ `panel.snapshot()` shares the same contract and names the same flag when the
9
+ baseline is missing.
10
+
11
+ ## 0.20.9
12
+
13
+ - **`dsh-plugin doctor` and `verify --no-mount` resolve a root export written as
14
+ a conditions object.** `exports["."]` can be a string or a conditions object
15
+ such as `{ "import": "./cli.mjs" }`; the loader still imports that target. It
16
+ used to be treated as "no root export", so a plugin whose conditions object
17
+ resolved to a CLI with no `apply` passed both checks. The failure now names
18
+ the resolved file, and a string root that exports `apply` still passes.
19
+ - **`verify --no-mount` no longer claims it imported a host half when it
20
+ skipped one.** A bundle that only inserts a subpath patch needs no root
21
+ module, so there is nothing for the loader to import. The success line used
22
+ to say "installed the tarball and imported its host half" anyway; it now says
23
+ the host import was skipped, so the line matches the check that actually ran.
24
+ - **`dsh-plugin explain --log` covers the Windows spelling of `~` and keeps a
25
+ missing log honest.** `~\.dsh\logs\install.log` expands the same way as
26
+ `~/.dsh/logs/install.log`, so the documented command works in PowerShell and
27
+ `cmd`; a log that cannot be read still exits `2` with the resolved absolute
28
+ path it tried, never a directory literally named `~`.
29
+
1
30
  ## 0.20.8
2
31
 
3
32
  - **`dsh-plugin release` resumes when the tag already points at HEAD.** A
package/README.md CHANGED
@@ -192,7 +192,7 @@ expectSnapshot(panel.html(), '__snapshots__', 'panel'); // throws with the ele
192
192
  await panel.unmount();
193
193
  ```
194
194
 
195
- First run writes nothing: it tells you to re-run with `UPDATE_SNAPSHOTS=1`, so a baseline is always a decision, never a side effect.
195
+ First run writes nothing: it tells you to re-run with `UPDATE_SNAPSHOTS=1`, so a baseline is always a decision, never a side effect. That rerun writes the normalised HTML and returns `{ status: 'written' }`; later runs return `same` or fail with the element that moved.
196
196
 
197
197
  ### Check what assistive tech sees
198
198
 
@@ -844,6 +844,11 @@ $ npx dsh-plugin-toolkit explain "plugin install failed" ./my-panel
844
844
  The same checkout argument works after the log:
845
845
  `dsh-plugin explain --log ~/.dsh/logs/install.log ./my-panel`.
846
846
 
847
+ On Windows, `cmd` and PowerShell leave the tilde alone:
848
+ `--log ~\.dsh\logs\install.log` expands exactly like
849
+ `--log ~/.dsh/logs/install.log`. A log that cannot be read exits `2` and names
850
+ the resolved absolute path it tried, never a directory literally named `~`.
851
+
847
852
  Text it does not recognise exits `2` instead of guessing: a wrong diagnosis
848
853
  sends you editing the wrong file. A log with no known cause also exits `2` and
849
854
  lists the causes it looked for.
@@ -858,7 +863,7 @@ ok packed 5 file(s), installed the tarball, mounted the panel
858
863
  My panel This panel came from dsh-plugin init. Clicks: 0
859
864
  ```
860
865
 
861
- It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. When the `files` list drops the panel:
866
+ It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. A bundle that only inserts a subpath patch needs no root module; in that case there is nothing to import, and the success line says it skipped the host import instead of claiming one ran. When the `files` list drops the panel:
862
867
 
863
868
  ```sh
864
869
  $ npx dsh-plugin-toolkit verify .
@@ -883,7 +888,9 @@ The install reports success and nothing shows up. In this order:
883
888
  node -e "import('my-plugin').then((m) => console.log(typeof m.apply))"
884
889
  ```
885
890
  `function` is what the loader needs. `undefined` means `exports["."]` points
886
- at the CLI — `0.8.0` of this tool shipped exactly that.
891
+ at the CLI — `0.8.0` of this tool shipped exactly that. A root written as a
892
+ conditions object (`{ "import": "./index.js" }`) is resolved before the
893
+ check, and `main` is only the fallback when no root export exists.
887
894
  3. **Does the tarball ship the panel?** `dsh-plugin verify .` installs what users
888
895
  get and mounts it. `doctor` cannot see this.
889
896
  4. **Is the patch row shaped right?** `cordis.patch.yml` needs one `- insert:`
@@ -977,7 +984,16 @@ Honest list, so nobody plans around a feature that does not exist:
977
984
  ## Changelog
978
985
 
979
986
  [`CHANGELOG.md`](CHANGELOG.md) lists what changed in each release, including
980
- the `0.20.8` fixes: `release` resumes when `plugin-v<version>` already points at
987
+ the `0.20.10` fix: `expectSnapshot()` and `panel.snapshot()` honor the
988
+ documented `UPDATE_SNAPSHOTS=1` rerun by writing the normalised HTML and
989
+ returning `{ status: "written" }`, while an ordinary run still fails a missing
990
+ or changed baseline rather than writing one as a side effect. The `0.20.9` fix
991
+ is recorded too: `explain --log` expands the Windows spelling
992
+ `~\.dsh\logs\install.log` exactly like `~/.dsh/logs/install.log`, so the
993
+ documented command works in PowerShell and `cmd`, and a log that cannot be read
994
+ exits `2` naming the resolved absolute path it tried instead of a directory
995
+ literally named `~`. The `0.20.8` fixes are recorded too: `release` resumes when
996
+ `plugin-v<version>` already points at
981
997
  HEAD — reusing the tag and continuing to the registry wait instead of failing —
982
998
  and refuses a tag at another commit, printing the tag, the commit it points at,
983
999
  HEAD and the exact `git tag -d` / `git push --delete` recovery commands. A
package/lib/cli.mjs CHANGED
@@ -8,7 +8,7 @@ import path from 'node:path';
8
8
 
9
9
  import { doctor } from './doctor.mjs';
10
10
  import { DEFAULT_ENGINES, doctorFix, fixEngines } from './fix.mjs';
11
- import { auditRemote, fixRemote } from './remote.mjs';
11
+ import { auditRemote, expandHome, fixRemote } from './remote.mjs';
12
12
  import { init } from './init.mjs';
13
13
  import { verify } from './verify.mjs';
14
14
  import { plan, release } from './release.mjs';
@@ -419,7 +419,7 @@ export async function run(argv, io = console, deps = {}) {
419
419
  let result;
420
420
 
421
421
  if (options.log !== undefined) {
422
- const logFile = path.resolve(options.log);
422
+ const logFile = path.resolve(expandHome(options.log));
423
423
  let log;
424
424
  try {
425
425
  log = fs.readFileSync(logFile, 'utf8');
@@ -475,7 +475,12 @@ export async function run(argv, io = console, deps = {}) {
475
475
  if (command === 'verify') {
476
476
  const result = await verify({ dir, mount: options.noMount !== true });
477
477
  if (result.ok === true) {
478
- const what = result.stage === 'mount' ? 'installed the tarball, mounted the panel' : 'installed the tarball and imported its host half';
478
+ const what =
479
+ result.stage === 'mount'
480
+ ? 'installed the tarball, mounted the panel'
481
+ : result.hostImported === true
482
+ ? 'installed the tarball and imported its host half'
483
+ : 'installed the tarball and skipped the host import, because there is no root export';
479
484
  io.log(`ok packed ${result.files.length} file(s), ${what}`);
480
485
  if (typeof result.text === 'string') io.log(` ${result.text}`);
481
486
  return 0;
package/lib/doctor.mjs CHANGED
@@ -123,12 +123,26 @@ export function checkPatchFile(dir, manifest) {
123
123
  return `dsh.bundle.patch points at ${bundle.patch}, which does not exist`;
124
124
  }
125
125
 
126
- /** `exports['./client']` is a string in some packages and a conditions object in others. */
126
+ /**
127
+ * `exports['./client']` is a string in some packages and a conditions object in
128
+ * others, and the root export can be either. Resolve the conditions Node or a
129
+ * bundler would use, including a nested object such as
130
+ * `{ node: { import: './index.mjs' } }`; an array's first resolvable
131
+ * alternative wins.
132
+ */
127
133
  export function exportTarget(value) {
128
134
  if (typeof value === 'string') return value;
135
+ if (Array.isArray(value)) {
136
+ for (const candidate of value) {
137
+ const target = exportTarget(candidate);
138
+ if (typeof target === 'string') return target;
139
+ }
140
+ return undefined;
141
+ }
129
142
  if (value !== null && typeof value === 'object') {
130
- for (const key of ['default', 'import', 'require']) {
131
- if (typeof value[key] === 'string') return value[key];
143
+ for (const key of ['default', 'import', 'require', 'node', 'module-sync']) {
144
+ const target = exportTarget(value[key]);
145
+ if (typeof target === 'string') return target;
132
146
  }
133
147
  }
134
148
  return undefined;
@@ -382,8 +396,17 @@ export function checkFilesList(manifest) {
382
396
  */
383
397
  /** The module the loader imports when it starts the bare package name. */
384
398
  export function rootEntry(manifest) {
385
- const root = typeof manifest.exports === 'object' && manifest.exports !== null ? manifest.exports['.'] : undefined;
386
- const entry = typeof root === 'string' ? root : manifest.main;
399
+ const exported = manifest.exports;
400
+ // A string `exports` is the root itself. A conditions object is only visible
401
+ // through `exports["."]`, and treating it as "no root" let a plugin whose
402
+ // root resolved to the CLI pass both doctor and verify.
403
+ const root =
404
+ typeof exported === 'string'
405
+ ? exported
406
+ : typeof exported === 'object' && exported !== null
407
+ ? exported['.']
408
+ : undefined;
409
+ const entry = exportTarget(root) ?? manifest.main;
387
410
  if (typeof entry !== 'string') return null;
388
411
  return entry.replace(/^\.\//, '');
389
412
  }
@@ -7,7 +7,7 @@
7
7
  import { createDom, installGlobals, requireFrom } from './env.mjs';
8
8
  import { createHost } from './host.mjs';
9
9
  import { loadBundle } from './load.mjs';
10
- import { compare, write } from './snapshot.mjs';
10
+ import { expectSnapshot, write } from './snapshot.mjs';
11
11
 
12
12
  function moduleShim(modules) {
13
13
  return (name) => {
@@ -213,16 +213,9 @@ export async function mountClient(options) {
213
213
  }
214
214
  return actual;
215
215
  },
216
- snapshot: (dir, name) => {
217
- const result = compare(dir, name, root.innerHTML);
218
- if (result.status === 'changed') {
219
- throw new Error(`${name} changed at <${result.actual.split(/(?=<)/)[result.firstDifference]}>`);
220
- }
221
- if (result.status === 'missing') {
222
- throw new Error(`${name} has no baseline at ${result.file}; run with --update to create it`);
223
- }
224
- return result;
225
- },
216
+ // Same contract as expectSnapshot: compare by default, write only when
217
+ // UPDATE_SNAPSHOTS=1 asks for it.
218
+ snapshot: (dir, name) => expectSnapshot(root.innerHTML, dir, name),
226
219
  writeSnapshot: (dir, name) => write(dir, name, root.innerHTML),
227
220
  unmount: async () => {
228
221
  await act(async () => {
@@ -53,6 +53,11 @@ export function write(dir, name, html) {
53
53
  export function expectSnapshot(html, dir, name) {
54
54
  const result = compare(dir, name, html);
55
55
  if (result.status === 'same') return result;
56
+ // Writing is opt-in: an ordinary run must never turn a missing or changed
57
+ // baseline into a pass. `UPDATE_SNAPSHOTS=1` is the documented decision.
58
+ if (process.env.UPDATE_SNAPSHOTS === '1') {
59
+ return { file: write(dir, name, html), status: 'written', actual: result.actual };
60
+ }
56
61
  if (result.status === 'missing') {
57
62
  throw new Error(`no baseline at ${result.file}; run with UPDATE_SNAPSHOTS=1 to create it`);
58
63
  }
package/lib/verify.mjs CHANGED
@@ -207,6 +207,10 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
207
207
  // and mounted nothing.
208
208
  const rootFile = rootEntry(report.manifest);
209
209
  let hostFace = null;
210
+ // A bundle that inserts a subpath plugin needs no root module, so there is
211
+ // nothing to import. The success line must not claim it imported a host half
212
+ // that was skipped.
213
+ let hostImported = false;
210
214
  if (rootFile !== null) {
211
215
  const absolute = path.join(installed, rootFile);
212
216
  if (fs.existsSync(absolute) === false) {
@@ -221,6 +225,7 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
221
225
  const { pathToFileURL } = await import('node:url');
222
226
  const loaded = await import(pathToFileURL(absolute).href);
223
227
  hostFace = loaded;
228
+ hostImported = true;
224
229
  if (typeof loaded.apply !== 'function') {
225
230
  return {
226
231
  ok: false,
@@ -261,7 +266,9 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
261
266
 
262
267
  // `--no-mount` skips the DOM, not the install: the host half is the half
263
268
  // that silently fails, and importing it needs nothing but Node.
264
- if (mount === false) return { ok: true, stage: 'pack', failures: [], files: packed.files, size: packed.size };
269
+ if (mount === false) {
270
+ return { ok: true, stage: 'pack', failures: [], files: packed.files, size: packed.size, hostImported };
271
+ }
265
272
 
266
273
  // Same convention the host uses: dsh.client.entry, then client.js.
267
274
  const entryFile = resolveEntry(installed, report.manifest);
@@ -304,7 +311,16 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
304
311
  installed,
305
312
  };
306
313
  }
307
- return { ok: true, stage: 'mount', failures: [], files: packed.files, size: packed.size, installed, text };
314
+ return {
315
+ ok: true,
316
+ stage: 'mount',
317
+ failures: [],
318
+ files: packed.files,
319
+ size: packed.size,
320
+ installed,
321
+ text,
322
+ hostImported,
323
+ };
308
324
  } catch (error) {
309
325
  return {
310
326
  ok: false,
@@ -316,5 +332,5 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
316
332
  }
317
333
  }
318
334
 
319
- return { ok: true, stage: 'install', failures: [], files: packed.files, size: packed.size, installed };
335
+ return { ok: true, stage: 'install', failures: [], files: packed.files, size: packed.size, installed, hostImported };
320
336
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.8",
3
+ "version": "0.20.10",
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": {