dsh-plugin-toolkit 0.20.42 → 0.20.44

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,64 @@
1
+ ## 0.20.44
2
+
3
+ - **`audit --home` reports a declared bundle whose `package.json` parses but has
4
+ no `dsh` field.** The install scan skipped every package without a `dsh` field
5
+ as an ordinary dependency, even when the profile named it in
6
+ `dsh.profile.bundles`. A profile that mounted one such broken bundle printed
7
+ "no plugins installed in any profile" and exited 0, so CI saw a clean profile
8
+ the loader could not mount. The scan now emits a `no dsh field` row with a
9
+ `dsh field` failure naming the declaring `package.json` and exits 1. Packages
10
+ the profile does not declare keep the old skip, so a profile containing only
11
+ ordinary dependencies still exits 0. `test/audit-home-no-dsh.test.mjs` pins
12
+ the ghost row and its exit status at the CLI beside a valid declared bundle
13
+ and a profile holding only ordinary dependencies, while `test/audit.test.mjs`
14
+ covers the row and the declared-name fallback.
15
+
16
+ ## 0.20.43
17
+
18
+ - **A host-aimed repair keeps the floor of a hyphen range that crosses the next
19
+ major.** `engines.dsh: "0.2.0 - 2.0.0"` plus `--host 0.3.0` could not carry
20
+ the appended `<1.0.0` comparator — npm only accepts the hyphen expression as
21
+ the whole branch — so the planner fell back to the host floor and wrote
22
+ `>=0.3.0 <1.0.0`, dropping the declared 0.2.x support. The hyphen branch is
23
+ now rewritten to its comparator form (`>=0.2.0 <1.0.0`), including partial
24
+ endpoints and a hyphen branch beside an alternation. `test/fix-host.test.mjs`
25
+ pins the local write, the alternation case, and the remote plan, asserting the
26
+ written range accepts the host and rejects one major above it.
27
+ - **Ships the host-aimed repair that 0.20.42 documented but was cut before it
28
+ merged.** The 0.20.42 entry below describes keeping the lower bound a plugin
29
+ already supports and capping each branch of an alternation range; the pull
30
+ request landed after that release was tagged, so installers of 0.20.42 still
31
+ got the old `>=0.3.0 <1.0.0` rewrite. This release is that change.
32
+
1
33
  ## 0.20.42
2
34
 
35
+ - **`audit --remote --host` names a malformed `engines.dsh` instead of calling
36
+ it missing.** A numeric or object value made `hostRange` return `null`, and
37
+ both the local check and the remote audit used the "missing" sentence, so the
38
+ report told an author to add a field that was already there while the host
39
+ answer stayed `unknown` without naming the real problem. The check now quotes
40
+ the value it cannot read (`engines.dsh 0.2 is not a string`), and a
41
+ non-object `engines` is named the same way. A truly absent or blank field
42
+ keeps the installer wording, and a readable range keeps its old verdict.
43
+ `test/audit-host.test.mjs` pins the remote path at the CLI, and
44
+ `test/doctor.test.mjs` pins both malformed shapes beside the missing-field
45
+ control.
46
+ - **A host-aimed repair keeps the range a plugin already supports, and
47
+ `doctor --fix --host` now aims a valid range that excludes the host.** The
48
+ fixer replaced any valid range with the host floor, so `engines.dsh:
49
+ ">=0.2.0"` plus `--host 0.3.0` became `>=0.3.0 <1.0.0` and silently dropped
50
+ every 0.2.x host the author had declared. It now keeps a lower bound that
51
+ already accepts the host and only adds the next-major ceiling, capping each
52
+ branch of an alternation range so `>=0.2.0 <0.4.0 || >=0.5.0` does not lose
53
+ its first branch; a range that already accepts the host and excludes the next
54
+ major is left alone. `doctor --fix --host` also planned nothing when `doctor`
55
+ accepted a range that still rejected the named host (`>=0.5.0` on 0.3.0),
56
+ because the plan only walked failed checks; an explicit `--host` or `--range`
57
+ is now a repair request through the same planner `fix --engines` uses, so the
58
+ two commands write the same range. `test/fix-host.test.mjs` pins the preserved
59
+ floor, the alternation branches, the no-op control, and the remote plan;
60
+ `test/doctor-fix.test.mjs` covers a valid but host-excluding range and an
61
+ explicit `--range`.
3
62
  - **`doctor --remote` and `audit --remote` name a `package.json` that is not a
4
63
  JSON object.** A manifest holding `null`, a string, a number or an array
5
64
  parses as JSON, but the remote reader moved on and either failed inside the
package/README.md CHANGED
@@ -327,8 +327,9 @@ directory still exits `0` with that line, and omitting `--home` still scans the
327
327
  default `~/.dsh`.
328
328
 
329
329
  Without `--host` the loaded column is `?`, because guessing would be worse than
330
- saying nothing. Only packages that declare a `dsh` field are audited — the rest of
331
- `node_modules` is ordinary dependencies, and auditing those is noise.
330
+ saying nothing. Only packages that declare a `dsh` field, plus packages the
331
+ profile names in `dsh.profile.bundles`, are audited — the rest of `node_modules`
332
+ is ordinary dependencies, and auditing those is noise.
332
333
 
333
334
  An installed package whose `package.json` cannot be read is the exception: the
334
335
  `dsh` field that would mark it as a plugin is in the file that failed to parse.
@@ -341,6 +342,13 @@ damaged `package.json` in a package that is neither in `dsh.profile.bundles` nor
341
342
  readable enough to expose a `dsh` field is still an ordinary dependency and is
342
343
  skipped, so one broken transitive install does not fail every audit.
343
344
 
345
+ A declared bundle can also parse but carry no `dsh` field at all. The profile
346
+ says the loader will mount it, so `audit` prints a `no dsh field` row with a
347
+ `dsh field` failure naming the declaring `package.json` and exits `1`, instead
348
+ of skipping the package and reporting the profile as having no plugins. The
349
+ skip still applies to a package that is not in `dsh.profile.bundles`; a profile
350
+ containing only ordinary dependencies prints no plugin rows and exits `0`.
351
+
344
352
  A declared bundle can also be missing entirely. If a name stays in
345
353
  `dsh.profile.bundles` after its `node_modules/<name>` folder is removed (an
346
354
  interrupted install, or a package deleted by hand), `audit` prints a `missing`
@@ -477,7 +485,7 @@ verdict, and the remaining entries are reported without another request.
477
485
 
478
486
  ### Will this plugin install on my DSH?
479
487
 
480
- The fifteen compatibility reports, from four repositories, all end with the same
488
+ The nineteen compatibility reports, from four repositories, all end with the same
481
489
  question. Add `--host <version>` to a remote audit and it answers that question
482
490
  for one repository. This is the output for `L3n3L/dsh-resume`, a real plugin
483
491
  whose declared range stops before DSH 0.2.0, checked against the
@@ -786,14 +794,15 @@ ok my-panel@1.0.0 (host >=0.2.0)
786
794
 
787
795
  The write is limited to the edits in the plan: a missing or non-range
788
796
  `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`.
797
+ and a range that already passes is not touched unless `--host` or `--range`
798
+ asks for a different one. `--range <range>` chooses the value to write, and
799
+ `--dry-run` wins if it is passed alongside `--write`.
792
800
 
793
801
  When the failed install names the host version, `--host` aims that repair at
794
802
  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:
803
+ decision as `fix --engines --host`, including when the declared range is valid
804
+ but excludes the host, so the preview shows the range and why the next major is
805
+ excluded, and `--write` applies exactly that edit:
797
806
 
798
807
  ```sh
799
808
  $ npx dsh-plugin-toolkit@latest doctor --fix ./my-panel --host 0.3.0
@@ -836,14 +845,19 @@ dsh-plugin fix: wrote engines.dsh ">=0.2.0" (was missing)
836
845
  A missing value, or one `doctor` calls "not a semver range", becomes `>=0.2.0` — the
837
846
  same range `init` writes. A range that already passes the check is left alone,
838
847
  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
848
+ uses; `--host` or `--range` can ask for a different one explicitly. `fix` changes only
840
849
  `engines.dsh` and leaves the other `engines` entries in place. `doctor` on its
841
850
  own still runs read-only, and its checks are unchanged; `fix` and `doctor --fix`
842
851
  change the manifest only when you pass `--write`.
843
852
 
844
853
  When the failed install names the host version, `--host` aims the range at that
845
854
  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:
855
+ before the next major, and the command prints that reasoning. A declared range
856
+ whose lower bound already accepts the host keeps that bound and only gains the
857
+ next-major ceiling (`>=0.2.0` with `--host 0.3.0` becomes
858
+ `>=0.2.0 <1.0.0`), applying that ceiling to each branch of an alternation range
859
+ so no branch the host supports is dropped; a declared range that already accepts
860
+ the host and excludes the next major is left alone:
847
861
 
848
862
  ```sh
849
863
  $ npx dsh-plugin-toolkit@latest fix ./my-panel --engines --host 0.3.0 --write
@@ -921,9 +935,12 @@ $ git apply /tmp/dsh-run-guard-engines.patch
921
935
  unless you pass `--force`; its output names the file, and the repository it read
922
936
  is still untouched. The same host-aware plan works with `--patch`:
923
937
  `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
938
+ `>=0.3.0 <1.0.0` for a manifest with no range and prints why; if the manifest
939
+ already declares a range that accepts the host, the remote plan keeps that lower
940
+ bound the same way the local fixer does (`>=0.2.0` becomes
941
+ `>=0.2.0 <1.0.0`). After cloning, `fix . --engines --host 0.3.0 --write`
942
+ applies that same range; either path writes one that accepts the host and
943
+ rejects the next major. The remote reader strips a UTF-8 BOM, so a manifest
927
944
  saved on Windows gives the same plan and the patch removes the BOM too. A
928
945
  `--host` or `--range` the planner cannot parse is refused before the GitHub
929
946
  read, so a typo names the flag instead of looking like a network failure or
package/lib/audit.mjs CHANGED
@@ -12,6 +12,7 @@ import os from 'node:os';
12
12
  import path from 'node:path';
13
13
 
14
14
  import {
15
+ checkDshField,
15
16
  checkHostCompatibility,
16
17
  doctor,
17
18
  hostRange,
@@ -138,6 +139,26 @@ function missingInstalled({ dir, name, profile }) {
138
139
  };
139
140
  }
140
141
 
142
+ /**
143
+ * A declared bundle whose `package.json` parses but has no `dsh` field. The
144
+ * folder is installed and `dsh.profile.bundles` names it, so the loader will
145
+ * look for a plugin definition that is not there. Skipping it as an ordinary
146
+ * dependency made a profile with one broken declared bundle report "no plugins
147
+ * installed" and exit 0, which is the false clean this record prevents.
148
+ */
149
+ function noDshInstalled({ dir, name, manifest, profile, manifestPath }) {
150
+ return {
151
+ dir,
152
+ // The profile's list is the name the loader will look for, so the row names
153
+ // the declared bundle even if its manifest omits `name` (or disagrees).
154
+ manifest: { ...manifest, name },
155
+ profile,
156
+ manifestPath,
157
+ noDsh: true,
158
+ error: checkDshField(manifest),
159
+ };
160
+ }
161
+
141
162
  /** Every package folder inside every profile, scoped names included. */
142
163
  export function listInstalled({ home = DEFAULT_HOME } = {}) {
143
164
  const root = resolvePath(home);
@@ -221,8 +242,16 @@ export function listInstalled({ home = DEFAULT_HOME } = {}) {
221
242
  continue;
222
243
  }
223
244
  // Only packages that declare themselves as plugins. node_modules is full
224
- // of ordinary dependencies, and auditing those is noise.
225
- if (manifest.dsh === undefined) continue;
245
+ // of ordinary dependencies, and auditing those is noise. A package the
246
+ // profile lists in `dsh.profile.bundles` is different: the profile says
247
+ // the loader will mount it, so a parsed manifest without a dsh field is
248
+ // a broken declared bundle, not an ordinary dependency to omit.
249
+ if (manifest.dsh === undefined) {
250
+ if (listedInProfile === true) {
251
+ found.push(noDshInstalled({ dir, name, manifest, profile, manifestPath }));
252
+ }
253
+ continue;
254
+ }
226
255
  found.push({ dir, manifest, profile });
227
256
  }
228
257
  }
@@ -823,60 +852,71 @@ export async function audit({
823
852
  }
824
853
 
825
854
  const profileFiles = new Map();
826
- const rows = installed.map(({ dir, manifest, profile, manifestPath, unreadable = false, missing = false, error }) => {
827
- let failures;
828
- if (missing === true) {
829
- // The folder is gone, so there is no manifest for doctor to read. The
830
- // profile record is the evidence, and the row must name the absent path.
831
- failures = [{ check: 'install', message: error }];
832
- } else if (unreadable === true) {
833
- // doctor would throw on the same file; keep the read error the install
834
- // scan already recorded so the row names the unreadable package.json.
835
- failures = [{ check: 'manifest', message: error }];
836
- } else {
837
- try {
838
- ({ failures } = doctor(dir, { installed: true }));
839
- } catch (caught) {
840
- failures = [{ check: 'manifest', message: caught.message }];
855
+ const rows = installed.map(
856
+ ({ dir, manifest, profile, manifestPath, unreadable = false, missing = false, noDsh = false, error }) => {
857
+ let failures;
858
+ if (missing === true) {
859
+ // The folder is gone, so there is no manifest for doctor to read. The
860
+ // profile record is the evidence, and the row must name the absent path.
861
+ failures = [{ check: 'install', message: error }];
862
+ } else if (unreadable === true) {
863
+ // doctor would throw on the same file; keep the read error the install
864
+ // scan already recorded so the row names the unreadable package.json.
865
+ failures = [{ check: 'manifest', message: error }];
866
+ } else if (noDsh === true) {
867
+ // The declared bundle's manifest parses, but there is no `dsh` field for
868
+ // the loader to mount. Say that once, in the same check name doctor uses.
869
+ failures = [{ check: 'dsh field', message: error ?? checkDshField(manifest) }];
870
+ } else {
871
+ try {
872
+ ({ failures } = doctor(dir, { installed: true }));
873
+ } catch (caught) {
874
+ failures = [{ check: 'manifest', message: caught.message }];
875
+ }
841
876
  }
842
- }
843
- const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
844
- let explanation = null;
845
- if (missing === true) {
846
- explanation = {
847
- reason: `dsh.profile.bundles lists it, but ${dir} is missing, so there is no installed copy to mount`,
848
- action: `reinstall ${manifest.name} (for example \`dsh plugin add ${manifest.name}\`), then restart the app`,
849
- };
850
- } else if (unreadable === true) {
851
- explanation = {
852
- reason: `${manifestPath} is unreadable, so the loader cannot tell what to mount`,
853
- action: `reinstall ${manifest.name} so its package.json is written completely`,
854
- };
855
- } else if (loaded === false) {
856
- if (profileFiles.has(profile) === false) {
857
- profileFiles.set(profile, readProfileBundles({ home, profile }));
877
+ const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
878
+ let explanation = null;
879
+ if (missing === true) {
880
+ explanation = {
881
+ reason: `dsh.profile.bundles lists it, but ${dir} is missing, so there is no installed copy to mount`,
882
+ action: `reinstall ${manifest.name} (for example \`dsh plugin add ${manifest.name}\`), then restart the app`,
883
+ };
884
+ } else if (unreadable === true) {
885
+ explanation = {
886
+ reason: `${manifestPath} is unreadable, so the loader cannot tell what to mount`,
887
+ action: `reinstall ${manifest.name} so its package.json is written completely`,
888
+ };
889
+ } else if (noDsh === true) {
890
+ explanation = {
891
+ reason: 'dsh.profile.bundles lists it, but its package.json parses with no "dsh" field, so the loader has nothing to mount',
892
+ action: `add dsh.bundle.patch to ${manifestPath} (and ship the patch file it names), or remove "${manifest.name}" from dsh.profile.bundles, then restart the app`,
893
+ };
894
+ } else if (loaded === false) {
895
+ if (profileFiles.has(profile) === false) {
896
+ profileFiles.set(profile, readProfileBundles({ home, profile }));
897
+ }
898
+ const listed = profileFiles.get(profile);
899
+ explanation = explainNotLoaded({
900
+ manifest,
901
+ name: manifest.name,
902
+ profileFile: listed.file,
903
+ bundles: listed.bundles,
904
+ });
858
905
  }
859
- const listed = profileFiles.get(profile);
860
- explanation = explainNotLoaded({
861
- manifest,
906
+ return {
862
907
  name: manifest.name,
863
- profileFile: listed.file,
864
- bundles: listed.bundles,
865
- });
866
- }
867
- return {
868
- name: manifest.name,
869
- version: manifest.version ?? '?',
870
- profile,
871
- dir,
872
- failures,
873
- ...split(failures),
874
- loaded,
875
- unreadable: unreadable === true,
876
- missing: missing === true,
877
- reason: explanation?.reason ?? null,
878
- action: explanation?.action ?? null,
879
- };
908
+ version: manifest.version ?? '?',
909
+ profile,
910
+ dir,
911
+ failures,
912
+ ...split(failures),
913
+ loaded,
914
+ unreadable: unreadable === true,
915
+ missing: missing === true,
916
+ noDsh: noDsh === true,
917
+ reason: explanation?.reason ?? null,
918
+ action: explanation?.action ?? null,
919
+ };
880
920
  });
881
921
 
882
922
  const width = Math.max(...rows.map((row) => row.name.length), 6);
@@ -887,15 +927,20 @@ export async function audit({
887
927
  ? 'missing'
888
928
  : row.unreadable === true
889
929
  ? 'unreadable'
890
- : row.loaded === null
891
- ? '?'
892
- : row.loaded === true
893
- ? 'loaded'
894
- : 'not loaded';
895
- const reason = row.missing === true || row.loaded === false || row.unreadable === true ? ` — ${row.reason}` : '';
930
+ : row.noDsh === true
931
+ ? 'no dsh field'
932
+ : row.loaded === null
933
+ ? '?'
934
+ : row.loaded === true
935
+ ? 'loaded'
936
+ : 'not loaded';
937
+ const reason =
938
+ row.missing === true || row.noDsh === true || row.loaded === false || row.unreadable === true
939
+ ? ` — ${row.reason}`
940
+ : '';
896
941
  io.log(`${row.name.padEnd(width)} ${String(row.version).padEnd(8)} ${state.padEnd(10)} ${describe(row)}${reason}`);
897
942
  for (const failure of row.failures) io.log(`${' '.repeat(width + 22)}${failure.check}: ${failure.message}`);
898
- if (row.missing === true || row.loaded === false || row.unreadable === true) {
943
+ if (row.missing === true || row.noDsh === true || row.loaded === false || row.unreadable === true) {
899
944
  io.log(`${detailIndent}fix: ${row.action}`);
900
945
  }
901
946
  }
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.44",
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": {