dsh-plugin-toolkit 0.20.42 → 0.20.43

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,5 +1,49 @@
1
+ ## 0.20.43
2
+
3
+ - **A host-aimed repair keeps the floor of a hyphen range that crosses the next
4
+ major.** `engines.dsh: "0.2.0 - 2.0.0"` plus `--host 0.3.0` could not carry
5
+ the appended `<1.0.0` comparator — npm only accepts the hyphen expression as
6
+ the whole branch — so the planner fell back to the host floor and wrote
7
+ `>=0.3.0 <1.0.0`, dropping the declared 0.2.x support. The hyphen branch is
8
+ now rewritten to its comparator form (`>=0.2.0 <1.0.0`), including partial
9
+ endpoints and a hyphen branch beside an alternation. `test/fix-host.test.mjs`
10
+ pins the local write, the alternation case, and the remote plan, asserting the
11
+ written range accepts the host and rejects one major above it.
12
+ - **Ships the host-aimed repair that 0.20.42 documented but was cut before it
13
+ merged.** The 0.20.42 entry below describes keeping the lower bound a plugin
14
+ already supports and capping each branch of an alternation range; the pull
15
+ request landed after that release was tagged, so installers of 0.20.42 still
16
+ got the old `>=0.3.0 <1.0.0` rewrite. This release is that change.
17
+
1
18
  ## 0.20.42
2
19
 
20
+ - **`audit --remote --host` names a malformed `engines.dsh` instead of calling
21
+ it missing.** A numeric or object value made `hostRange` return `null`, and
22
+ both the local check and the remote audit used the "missing" sentence, so the
23
+ report told an author to add a field that was already there while the host
24
+ answer stayed `unknown` without naming the real problem. The check now quotes
25
+ the value it cannot read (`engines.dsh 0.2 is not a string`), and a
26
+ non-object `engines` is named the same way. A truly absent or blank field
27
+ keeps the installer wording, and a readable range keeps its old verdict.
28
+ `test/audit-host.test.mjs` pins the remote path at the CLI, and
29
+ `test/doctor.test.mjs` pins both malformed shapes beside the missing-field
30
+ control.
31
+ - **A host-aimed repair keeps the range a plugin already supports, and
32
+ `doctor --fix --host` now aims a valid range that excludes the host.** The
33
+ fixer replaced any valid range with the host floor, so `engines.dsh:
34
+ ">=0.2.0"` plus `--host 0.3.0` became `>=0.3.0 <1.0.0` and silently dropped
35
+ every 0.2.x host the author had declared. It now keeps a lower bound that
36
+ already accepts the host and only adds the next-major ceiling, capping each
37
+ branch of an alternation range so `>=0.2.0 <0.4.0 || >=0.5.0` does not lose
38
+ its first branch; a range that already accepts the host and excludes the next
39
+ major is left alone. `doctor --fix --host` also planned nothing when `doctor`
40
+ accepted a range that still rejected the named host (`>=0.5.0` on 0.3.0),
41
+ because the plan only walked failed checks; an explicit `--host` or `--range`
42
+ is now a repair request through the same planner `fix --engines` uses, so the
43
+ two commands write the same range. `test/fix-host.test.mjs` pins the preserved
44
+ floor, the alternation branches, the no-op control, and the remote plan;
45
+ `test/doctor-fix.test.mjs` covers a valid but host-excluding range and an
46
+ explicit `--range`.
3
47
  - **`doctor --remote` and `audit --remote` name a `package.json` that is not a
4
48
  JSON object.** A manifest holding `null`, a string, a number or an array
5
49
  parses as JSON, but the remote reader moved on and either failed inside the
package/README.md CHANGED
@@ -477,7 +477,7 @@ verdict, and the remaining entries are reported without another request.
477
477
 
478
478
  ### Will this plugin install on my DSH?
479
479
 
480
- The fifteen compatibility reports, from four repositories, all end with the same
480
+ The nineteen compatibility reports, from four repositories, all end with the same
481
481
  question. Add `--host <version>` to a remote audit and it answers that question
482
482
  for one repository. This is the output for `L3n3L/dsh-resume`, a real plugin
483
483
  whose declared range stops before DSH 0.2.0, checked against the
@@ -786,14 +786,15 @@ ok my-panel@1.0.0 (host >=0.2.0)
786
786
 
787
787
  The write is limited to the edits in the plan: a missing or non-range
788
788
  `engines.dsh` becomes `>=0.2.0`, the other `engines` entries are left in place,
789
- and a range that already passes is not touched. `--range <range>` chooses the
790
- value used when `engines.dsh` needs repair, and `--dry-run` wins if it is passed
791
- alongside `--write`.
789
+ and a range that already passes is not touched unless `--host` or `--range`
790
+ asks for a different one. `--range <range>` chooses the value to write, and
791
+ `--dry-run` wins if it is passed alongside `--write`.
792
792
 
793
793
  When the failed install names the host version, `--host` aims that repair at
794
794
  the DSH that rejected it instead of falling back to the default. It is the same
795
- decision as `fix --engines --host`, so the preview shows the range and why the
796
- next major is excluded, and `--write` applies exactly that edit:
795
+ decision as `fix --engines --host`, including when the declared range is valid
796
+ but excludes the host, so the preview shows the range and why the next major is
797
+ excluded, and `--write` applies exactly that edit:
797
798
 
798
799
  ```sh
799
800
  $ npx dsh-plugin-toolkit@latest doctor --fix ./my-panel --host 0.3.0
@@ -836,14 +837,19 @@ dsh-plugin fix: wrote engines.dsh ">=0.2.0" (was missing)
836
837
  A missing value, or one `doctor` calls "not a semver range", becomes `>=0.2.0` — the
837
838
  same range `init` writes. A range that already passes the check is left alone,
838
839
  because `>=0.3.0` can be a deliberate statement about the host APIs the plugin
839
- uses; `--range <range>` asks for a different one explicitly. `fix` changes only
840
+ uses; `--host` or `--range` can ask for a different one explicitly. `fix` changes only
840
841
  `engines.dsh` and leaves the other `engines` entries in place. `doctor` on its
841
842
  own still runs read-only, and its checks are unchanged; `fix` and `doctor --fix`
842
843
  change the manifest only when you pass `--write`.
843
844
 
844
845
  When the failed install names the host version, `--host` aims the range at that
845
846
  host instead of using the default. The written range accepts the host and stops
846
- before the next major, and the command prints that reasoning:
847
+ before the next major, and the command prints that reasoning. A declared range
848
+ whose lower bound already accepts the host keeps that bound and only gains the
849
+ next-major ceiling (`>=0.2.0` with `--host 0.3.0` becomes
850
+ `>=0.2.0 <1.0.0`), applying that ceiling to each branch of an alternation range
851
+ so no branch the host supports is dropped; a declared range that already accepts
852
+ the host and excludes the next major is left alone:
847
853
 
848
854
  ```sh
849
855
  $ npx dsh-plugin-toolkit@latest fix ./my-panel --engines --host 0.3.0 --write
@@ -921,9 +927,12 @@ $ git apply /tmp/dsh-run-guard-engines.patch
921
927
  unless you pass `--force`; its output names the file, and the repository it read
922
928
  is still untouched. The same host-aware plan works with `--patch`:
923
929
  `fix <owner>/<repo> --remote --engines --host 0.3.0 --patch repair.patch` plans
924
- `>=0.3.0 <1.0.0` and prints why. After cloning, `fix . --engines --host 0.3.0
925
- --write` applies that same range; either path writes one that accepts the host
926
- and rejects the next major. The remote reader strips a UTF-8 BOM, so a manifest
930
+ `>=0.3.0 <1.0.0` for a manifest with no range and prints why; if the manifest
931
+ already declares a range that accepts the host, the remote plan keeps that lower
932
+ bound the same way the local fixer does (`>=0.2.0` becomes
933
+ `>=0.2.0 <1.0.0`). After cloning, `fix . --engines --host 0.3.0 --write`
934
+ applies that same range; either path writes one that accepts the host and
935
+ rejects the next major. The remote reader strips a UTF-8 BOM, so a manifest
927
936
  saved on Windows gives the same plan and the patch removes the BOM too. A
928
937
  `--host` or `--range` the planner cannot parse is refused before the GitHub
929
938
  read, so a typo names the flag instead of looking like a network failure or
package/lib/cli.mjs CHANGED
@@ -483,7 +483,13 @@ export async function run(argv, io = console, deps = {}) {
483
483
  return 0;
484
484
  }
485
485
 
486
- io.log(`dsh-plugin doctor --fix: ${result.plan.length} failed check(s) in ${result.dir}`);
486
+ // An explicit --host/--range can ask for a repair while every doctor check
487
+ // passes (a valid range that excludes the host). Calling that a failed
488
+ // check would blame a check that did not fail.
489
+ const failedChecks = result.before.failures.length;
490
+ io.log(
491
+ `dsh-plugin doctor --fix: ${result.plan.length} ${failedChecks === 0 ? 'requested repair(s)' : 'failed check(s)'} in ${result.dir}`,
492
+ );
487
493
  for (const entry of result.plan) {
488
494
  if (entry.kind === 'edit') {
489
495
  io.log(` ✗ ${entry.check}: ${entry.path} — would write ${entry.edit}`);
package/lib/doctor.mjs CHANGED
@@ -166,6 +166,19 @@ export function checkDshField(manifest) {
166
166
  }
167
167
 
168
168
  export function checkHostRange(manifest) {
169
+ const engines = manifest?.engines;
170
+ if (engines !== undefined && engines !== null && (typeof engines !== 'object' || Array.isArray(engines) === true)) {
171
+ // `"engines": ">=0.2.0"` is the string instead of the object npm reads.
172
+ // Without this branch every caller falls through to hostRange() === null and
173
+ // tells the author to add an `engines.dsh` field that is already present.
174
+ return 'package.json "engines" is not an object, so it cannot declare a dsh range';
175
+ }
176
+ const dsh = engines?.dsh;
177
+ if (typeof dsh !== 'undefined' && dsh !== null && typeof dsh !== 'string') {
178
+ // A number or object here is malformed, not absent: quoting the value back
179
+ // is the difference between "add the field" and "fix the field you wrote".
180
+ return `engines.dsh ${JSON.stringify(dsh)} is not a string, so no host can compare its version against it`;
181
+ }
169
182
  const range = hostRange(manifest);
170
183
  if (range === null) return 'engines.dsh is missing, so the market index cannot state the host requirement';
171
184
  if (isRangeExpression(range) === false) return `engines.dsh "${range}" is not a semver range`;
package/lib/fix.mjs CHANGED
@@ -15,7 +15,7 @@
15
15
  import fs from 'node:fs';
16
16
  import path from 'node:path';
17
17
 
18
- import { hostRangePlan, satisfiesRange } from './compat.mjs';
18
+ import { hostRangePlan, parsePartialVersion, satisfiesRange } from './compat.mjs';
19
19
  import { checkHostRange, doctor, hostRange, readManifestSource, stripBom } from './doctor.mjs';
20
20
  import { resolvePath } from './paths.mjs';
21
21
 
@@ -96,6 +96,69 @@ export function isHostRange(value) {
96
96
  return checkHostRange({ engines: { dsh: value } }) === null;
97
97
  }
98
98
 
99
+ /**
100
+ * Cap one branch at the next major, whatever syntax the author used.
101
+ *
102
+ * Appending `<nextMajor` works for a comparator set, but npm's hyphen syntax
103
+ * (`0.2.0 - 2.0.0`) only accepts the hyphen expression as the whole branch, so
104
+ * `${branch} <1.0.0` did not parse. The caller then gave up on the floor and
105
+ * proposed the host floor, silently dropping every host the hyphen range
106
+ * already supported. A hyphen branch reaching this helper necessarily includes
107
+ * the next major, so replacing its upper endpoint with the next-major ceiling
108
+ * keeps the declared lower bound and drops only the versions above the cap.
109
+ */
110
+ function cappedHyphenBranch(branch, nextMajor) {
111
+ const match = /^(\S+)\s+-\s+(\S+)$/u.exec(branch);
112
+ if (match === null) return null;
113
+ const start = parsePartialVersion(match[1]);
114
+ // The upper endpoint only has to be a valid version for the branch to parse;
115
+ // this helper is called only when the branch already accepts nextMajor, so
116
+ // the ceiling replaces that endpoint rather than being appended after it.
117
+ if (start === null || parsePartialVersion(match[2]) === null) return null;
118
+ if (start.major === null) return `<${nextMajor}`;
119
+ const core = `${start.major}.${start.minor ?? 0}.${start.patch ?? 0}`;
120
+ const lower = start.prerelease.length > 0 ? `${core}-${start.prerelease.join('.')}` : core;
121
+ return `>=${lower} <${nextMajor}`;
122
+ }
123
+
124
+ /**
125
+ * Keep the lower bound a plugin already declares and add a next-major ceiling.
126
+ *
127
+ * Aiming at a host must not silently drop hosts the author already supports:
128
+ * `>=0.2.0` plus `--host 0.3.0` is `>=0.2.0 <1.0.0`, not `>=0.3.0 <1.0.0`.
129
+ * npm's semver has no parentheses, so a single trailing ceiling would cap only
130
+ * the last alternation branch; cap each branch instead. Every branch is an
131
+ * AND-set, so appending a comparator narrows that branch without changing which
132
+ * host it started with. A hyphen branch needs the comparator form (see
133
+ * `cappedHyphenBranch`) because npm only accepts the hyphen as the whole branch.
134
+ */
135
+ function cappedAtNextMajor(current, nextMajor, host) {
136
+ const base = typeof current === 'string' ? current.trim() : '';
137
+ if (base === '') return null;
138
+ const branches = base.split('||').map((branch) => branch.trim());
139
+ if (branches.some((branch) => branch === '')) return null;
140
+ const capped = [];
141
+ for (const branch of branches) {
142
+ if (satisfiesRange(branch, nextMajor) === false) {
143
+ capped.push(branch);
144
+ continue;
145
+ }
146
+ // A branch that does not overlap the host (the other side of an
147
+ // alternation) still has to stay in the result; only the joined candidate
148
+ // is checked for whether one branch keeps the host.
149
+ const straight = `${branch} <${nextMajor}`;
150
+ if (isHostRange(straight) === true) {
151
+ capped.push(straight);
152
+ continue;
153
+ }
154
+ const hyphen = cappedHyphenBranch(branch, nextMajor);
155
+ if (hyphen === null || isHostRange(hyphen) === false) return null;
156
+ capped.push(hyphen);
157
+ }
158
+ const candidate = capped.join(' || ');
159
+ return isHostRange(candidate) === true && satisfiesRange(candidate, host) === true ? candidate : null;
160
+ }
161
+
99
162
  function failure(check, message) {
100
163
  return { ok: false, failures: [{ check, message }] };
101
164
  }
@@ -133,10 +196,34 @@ export function planEnginesEdit(manifest, { range, host, force = false } = {}) {
133
196
  if (requested.ok !== true) {
134
197
  return requested;
135
198
  }
136
- const { proposed } = requested;
137
199
 
138
200
  const current = hostRange(manifest);
139
201
  const correct = current !== null && checkHostRange(manifest) === null;
202
+ let proposed = requested.proposed;
203
+ let why = requested.why;
204
+
205
+ // A host already accepted by a valid range is not a reason to throw away the
206
+ // range's floor. Keep it and add the next-major ceiling; when the range
207
+ // already excludes the next major there is nothing left to repair.
208
+ const explicitRange = range !== undefined && range !== null;
209
+ if (requested.host !== null && explicitRange === false && correct === true) {
210
+ const includesHost = satisfiesRange(current, requested.host);
211
+ if (includesHost === true) {
212
+ const nextMajor = requested.nextMajor;
213
+ const excludesNextMajor = nextMajor !== null && satisfiesRange(current, nextMajor) === false;
214
+ if (excludesNextMajor === true) {
215
+ proposed = current;
216
+ why = `host ${requested.host} is already inside "${current}" and ${nextMajor} is excluded, so the declared range already accepts the host you run`;
217
+ } else if (nextMajor !== null) {
218
+ const capped = cappedAtNextMajor(current, nextMajor, requested.host);
219
+ if (capped !== null) {
220
+ proposed = capped;
221
+ why = `host ${requested.host} is inside "${current}"; keeping that lower bound and adding <${nextMajor} accepts the host and excludes the next major`;
222
+ }
223
+ }
224
+ }
225
+ }
226
+
140
227
  const same = normalize(current) === normalize(proposed);
141
228
  const forced = force === true || requested.force === true;
142
229
  const noop = correct === true && (forced !== true || same === true);
@@ -158,7 +245,7 @@ export function planEnginesEdit(manifest, { range, host, force = false } = {}) {
158
245
  reason: noop === true ? 'already-correct' : current === null ? 'missing' : correct === true ? 'different' : 'not-a-range',
159
246
  host: requested.host,
160
247
  nextMajor: requested.nextMajor,
161
- why: requested.why,
248
+ why,
162
249
  };
163
250
  }
164
251
 
@@ -491,6 +578,12 @@ function setField(target, field, value) {
491
578
  * `kind: 'edit'` means `doctor --fix --write` can make the change; `kind:
492
579
  * 'manual'` means the check failed but guessing the right file contents would
493
580
  * be worse than saying so. A plan is pure: it never writes.
581
+ *
582
+ * A named `--host` or `--range` is also a repair request when `doctor` passes:
583
+ * a range can be valid and still exclude the DSH that rejected the install
584
+ * (`engines.dsh: ">=0.5.0"` on a 0.3.0 host), and `doctor` has no host to
585
+ * compare against. The same shared planner as `fix --engines` decides that
586
+ * edit, so the two commands cannot disagree about which range to write.
494
587
  */
495
588
  export function repairPlan({ dir = '.', range, host } = {}) {
496
589
  const target = resolvePath(dir);
@@ -511,30 +604,41 @@ export function repairPlan({ dir = '.', range, host } = {}) {
511
604
  return failure('manifest', error instanceof Error ? error.message : String(error));
512
605
  }
513
606
 
514
- const plan = report.failures.map((entry) => {
515
- if (entry.check === 'engines.dsh') {
516
- const current = hostRange(report.manifest);
517
- const reason = current === null ? 'missing' : 'not-a-range';
518
- return {
519
- check: entry.check,
520
- kind: 'edit',
521
- file: manifestPath,
522
- path: path.basename(manifestPath),
523
- field: 'engines.dsh',
524
- before: current,
525
- after: proposed,
526
- reason,
527
- edit: `engines.dsh "${proposed}" (was ${current === null ? 'missing' : `"${current}"`})`,
528
- message: entry.message,
529
- };
530
- }
531
- return {
607
+ const edit = planEnginesEdit(report.manifest, {
608
+ range,
609
+ host,
610
+ // Asking for a range or host explicitly is the same request `fix
611
+ // --engines` accepts: replace even a valid range the author declared.
612
+ force: range !== undefined || host !== undefined,
613
+ });
614
+ if (edit.ok !== true) return edit;
615
+
616
+ const enginesFailure = report.failures.find((entry) => entry.check === 'engines.dsh');
617
+ const plan = [];
618
+ if (edit.noop !== true) {
619
+ const before = edit.current === null ? 'missing' : `"${edit.current}"`;
620
+ plan.push({
621
+ check: 'engines.dsh',
622
+ kind: 'edit',
623
+ file: manifestPath,
624
+ path: path.basename(manifestPath),
625
+ field: 'engines.dsh',
626
+ before: edit.current,
627
+ after: edit.proposed,
628
+ reason: edit.reason,
629
+ edit: `engines.dsh "${edit.proposed}" (was ${before})`,
630
+ message: enginesFailure?.message ?? edit.why ?? 'engines.dsh does not accept the named host',
631
+ });
632
+ }
633
+ for (const entry of report.failures) {
634
+ if (entry.check === 'engines.dsh') continue;
635
+ plan.push({
532
636
  check: entry.check,
533
637
  kind: 'manual',
534
638
  message: entry.message,
535
639
  ...manualRepair(entry, target, report.manifest),
536
- };
537
- });
640
+ });
641
+ }
538
642
 
539
643
  return {
540
644
  ok: true,
@@ -544,9 +648,9 @@ export function repairPlan({ dir = '.', range, host } = {}) {
544
648
  plan,
545
649
  edits: plan.filter((entry) => entry.kind === 'edit'),
546
650
  manual: plan.filter((entry) => entry.kind === 'manual'),
547
- host: requested.host,
548
- nextMajor: requested.nextMajor,
549
- why: requested.why,
651
+ host: edit.host,
652
+ nextMajor: edit.nextMajor,
653
+ why: edit.why,
550
654
  };
551
655
  }
552
656
 
package/lib/remote.mjs CHANGED
@@ -436,8 +436,22 @@ export async function auditRemote(
436
436
 
437
437
  // `engines.dsh` deserves the wording the installer actually uses: a host that
438
438
  // enforces the range refuses the install outright, which is the issue text
439
- // maintainers paste into their own tracker.
440
- if (enginesCheck !== null && hostRange(manifest) === null) {
439
+ // maintainers paste into their own tracker. Only a genuinely absent or blank
440
+ // field gets the "missing" wording: a value of the wrong JSON type is
441
+ // malformed, and the checkHostRange message names the value instead of asking
442
+ // the author to add a field that is already there.
443
+ const enginesField = manifest.engines;
444
+ const enginesIsObject =
445
+ enginesField !== null && typeof enginesField === 'object' && Array.isArray(enginesField) === false;
446
+ const declaredDsh = enginesIsObject === true ? enginesField.dsh : undefined;
447
+ const hostRangeAbsent =
448
+ enginesField === undefined ||
449
+ enginesField === null ||
450
+ (enginesIsObject === true &&
451
+ (declaredDsh === undefined ||
452
+ declaredDsh === null ||
453
+ (typeof declaredDsh === 'string' && declaredDsh.trim() === '')));
454
+ if (enginesCheck !== null && hostRangeAbsent === true) {
441
455
  const index = failures.findIndex((entry) => entry.check === 'engines.dsh');
442
456
  if (index !== -1) {
443
457
  failures[index] = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.42",
3
+ "version": "0.20.43",
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": {