dsh-plugin-toolkit 0.20.34 → 0.20.36

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,88 @@
1
+ ## 0.20.36
2
+
3
+ - **`audit --remote` no longer reads an arbitrary `build` script as a pre-pack
4
+ hook.** The remote audit skipped the patch, client and root-export file
5
+ checks whenever `scripts` had a `build` entry, but npm never runs a plain
6
+ `build` script during `npm pack`; only its lifecycle hooks do. A repository
7
+ whose only hook was `scripts.build` therefore passed with no `client.js` in
8
+ the tree even though the tarball contained no bundle either. Build evidence
9
+ now comes only from `prepack` and `prepare` (which run for `npm pack`) and
10
+ `prepublishOnly` (which runs before `npm publish` packs), and an empty hook
11
+ is not evidence. `test/audit-remote-build-hooks.test.mjs` crosses both
12
+ process boundaries: it asks npm what three build-only fixtures actually
13
+ ship, runs the shipped CLI against the same committed tree, and requires exit
14
+ `1` with a failure naming `client.js`; each fixture's `build` script would
15
+ create the client if npm ran it, so the test also proves `npm pack` leaves it
16
+ alone. A `prepack` fixture and a `prepare` fixture that create the file in
17
+ the tarball still exit `0` with the skipped-files note, and a committed
18
+ client beside a `build` script stays clean without the built note. The
19
+ README and `docs/repair.md` state the same rule.
20
+
21
+ ## 0.20.35
22
+
23
+ - **The compatibility answer now has a reproducible machine-readable form.**
24
+ The README's "Will this plugin install on my DSH?" section already showed
25
+ the real `audit --remote --host` output for `L3n3L/dsh-resume@0.1.3` from the
26
+ checked-in snapshot; it now also shows
27
+ `node scripts/compatibility-sample.mjs --json`. `scripts/compatibility-sample.mjs`
28
+ gains the `--json` form of the same replay, so both the human line and the CI
29
+ object come from the shipped executable. The section spells out that an
30
+ incompatible range is reported through `compatibility` (and the exit code)
31
+ rather than an extra `failures` entry, so a consumer that counts only
32
+ `failures.length` cannot mistake a host mismatch for a clean object.
33
+ `test/readme-compatibility.test.mjs` compares both documentation blocks with
34
+ the script's output and pins the JSON shape.
35
+
36
+ - **A blank remote `--host` gets the same refusal as any other invalid
37
+ version.** `audit --remote owner/repo --host ' '` and the batch form used
38
+ to fall through the generic "running app URL" hint because the value was
39
+ empty, while the exported audit functions reported the complete-version
40
+ sentence. The CLI now identifies the remote form before it resolves the
41
+ target, the jobs or a list file, and routes blank and whitespace values
42
+ through `hostVersionIssue()`; the host check also runs before `--jobs`
43
+ parsing. The single-target and `--from` forms are pinned with their
44
+ valid-host controls in `test/audit-remote-host-invalid.test.mjs`: the
45
+ real-list invalid case, the shared blank message, the shipped batch exit
46
+ code, and the `compatible` control.
47
+
48
+ - **A host-aimed repair can no longer write a range that excludes the host.**
49
+ `fix --engines --host 0.3.0 --range ">=0.5.0"` printed `host 0.3.0 is not
50
+ inside the explicit range`, then wrote `>=0.5.0` and exited `0` — the same
51
+ install failure if it was applied. The local fixer, `doctor --fix` and
52
+ `fix --remote` now share the same decision: an explicit `--range` wins only
53
+ when it accepts the named host, and a contradictory pair is a usage error
54
+ before anything is written or any GitHub request is made. The message names
55
+ both values, explains npm's pre-release rule when that is the only reason the
56
+ host is excluded, and points at dropping `--range` to aim the range
57
+ automatically. `fix --remote --host banana --write` also names the bad host
58
+ instead of the read-only refusal, and that refusal now names `--patch` as the
59
+ way to save the repair for a checkout. `test/fix-host-conflict.test.mjs`
60
+ pins the local, `doctor --fix` and remote paths, the accepting-range control,
61
+ and re-applies a remote patch to assert the written range accepts `0.3.0` and
62
+ rejects `1.0.0`.
63
+
64
+ - **The remote audit refuses an invalid `--host` before any read, whichever
65
+ entry point is used.** The CLI already stopped `--host banana` with exit `2`,
66
+ but `auditRemote()` and `auditRemoteTargets()` — the single-target and batch
67
+ paths the command delegates to — still accepted it, read GitHub and answered
68
+ `compatibility: "unknown"`. All three now share `hostVersionIssue()`, so a
69
+ value that is not a complete DSH version is rejected before the repository or
70
+ a `--from` list is read. The acceptance case
71
+ (`audit --remote acme/clean --host banana --json`) is pinned: exit `2`, the
72
+ message names `--host` and `banana`, stdout stays empty and the mocked fetch
73
+ is never called; `--host 0.2.0` still exits `0` with `compatible`. The
74
+ regression test covers the CLI, both exported fan-out functions and a batch
75
+ whose list file must not be opened.
76
+
77
+ - **`audit --remote --host` no longer claims a range it never read.** A
78
+ repository GitHub answered with a 500 or skipped after a rate limit was
79
+ printed as `unknown with dsh <version>; declares no engines.dsh range`, even
80
+ though `package.json` was never read. The host fields are now attached only
81
+ when a manifest exists, so unreadable and rate-limited rows keep their own
82
+ verdict without a fabricated range or compatibility answer. The regression
83
+ test pins the unreadable row, the skipped batch row and a readable control
84
+ that still gets `compatible`.
85
+
1
86
  ## 0.20.34
2
87
 
3
88
  - **`audit --remote` names every finding the same way and never reads a
package/README.md CHANGED
@@ -435,10 +435,13 @@ What it can see, and what it cannot:
435
435
  declares. A repository whose checkout fails `readme` fails the remote check
436
436
  too, with the same sentence.
437
437
  - 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.
438
+ root export `apply`) need the tree. npm runs `prepack` and `prepare` before
439
+ `npm pack` creates the tarball, and `prepublishOnly` before `npm publish`
440
+ does, so a package whose lifecycle hook builds those files publishes files it
441
+ does not commit: those checks are **skipped with a note** instead of calling a
442
+ working plugin broken. A plain `build` script is not a lifecycle hook and is
443
+ not evidence by itself, because npm never runs it unless `prepack` or
444
+ `prepare` calls it; put the build there if it produces shipped files.
442
445
  - Public repositories work anonymously, but GitHub allows 60 requests an hour.
443
446
  Export `GH_TOKEN` (or `GITHUB_TOKEN`) to audit more than one or two.
444
447
 
@@ -501,6 +504,31 @@ sample audits the repository's current default branch instead; a README or
501
504
  manifest change since 0.1.3 can add another `readme` or manifest failure to the
502
505
  same row.
503
506
 
507
+ CI should read the same answer as data. This is the reproducible sample again,
508
+ with the flag that changes the form rather than the verdict:
509
+
510
+ ```sh
511
+ $ node scripts/compatibility-sample.mjs --json
512
+ [
513
+ {
514
+ "target": "L3n3L/dsh-resume",
515
+ "version": "0.1.3",
516
+ "hostRange": ">=0.1.0-rc.6 <0.2.0-0",
517
+ "failures": [],
518
+ "notes": [],
519
+ "host": "0.2.2-alpha.3",
520
+ "compatibility": "incompatible"
521
+ }
522
+ ]
523
+ ```
524
+
525
+ `compatibility` is the finding for an incompatible range; the object does not
526
+ invent a second entry in `failures` for the same fact. Gate on `compatibility`
527
+ or the process exit code, not on `failures.length` alone, or a host mismatch
528
+ will look clean. The command still exits `1`, and the test suite compares this
529
+ block with the JSON the executable prints, so the documented shape cannot drift
530
+ from the code that emits it.
531
+
504
532
  The line carries the range `package.json` declares and one of `compatible`,
505
533
  `incompatible`, or `unknown` against that host version. `unknown` is the honest
506
534
  answer for a missing or malformed range — there is nothing to compare — while a
@@ -525,12 +553,16 @@ A bare `--host` is a usage error, not an audit without the comparison: the
525
553
  command exits `2` before it reads GitHub, and `--host --json` does not consume
526
554
  the `--json` flag as a version. The value itself must be a complete version
527
555
  (`0.2.2`, `v0.2.2`, or `0.2.2-alpha.3`): a range (`>=0.2.0`), a partial version
528
- (`0.2`), or a tag name is rejected with exit `2` before any repository is read,
529
- so a typo cannot turn into a clean-looking `unknown` row.
556
+ (`0.2`), a tag name, or a blank value is rejected with exit `2` before any
557
+ repository is read or the `--from` list is opened, so a typo cannot turn into a
558
+ clean-looking `unknown` row. The single-target and batch forms use the same
559
+ check and the same message.
530
560
 
531
561
  `--host` still names the running app URL for a local `audit`; on `--remote` it
532
- is the DSH version to compare against. With `--json`, each finding gains
533
- `host` and `compatibility` beside `hostRange`.
562
+ is the DSH version to compare against. With `--json`, each finding whose
563
+ manifest was read gains `host` and `compatibility` beside `hostRange`; an
564
+ unreadable or rate-limited repository has no manifest to compare, so it keeps
565
+ its own verdict and does not invent a range or an `unknown` answer.
534
566
 
535
567
  Each repository gets one line with its verdict — `clean`, `failing`,
536
568
  `unreadable`, or `rate-limited` — and the run ends with a counted summary:
@@ -628,11 +660,11 @@ $ dsh-plugin audit --remote --from repos.txt --json
628
660
  Every repository produces one object with `target`, `version`, `hostRange`,
629
661
  `failures` (`{ check, message }`) and `notes`, and the command exits `1` when any
630
662
  repository has a problem. With `--host <version>` each object also carries
631
- `host` and `compatibility`. A rate-limited repository adds `rateLimited: true`
632
- and a `rateLimit` object with the HTTP `status` and, when GitHub sent one,
633
- `resetAt`; it is not marked `unreadable`. A network error is printed in `notes`
634
- and still exits `1`: a repository the tool could not read is never reported as
635
- clean. Packages that build before they pack
663
+ `host` and `compatibility` once its manifest was read. A rate-limited
664
+ repository adds `rateLimited: true` and a `rateLimit` object with the HTTP
665
+ `status` and, when GitHub sent one, `resetAt`; it is not marked `unreadable`. A
666
+ network error is printed in `notes` and still exits `1`: a repository the tool
667
+ could not read is never reported as clean. Packages that build before they pack
636
668
  keep their file-level checks in `notes` as before.
637
669
 
638
670
  When the list is a repair queue rather than a report, add `--patch-dir`:
@@ -762,7 +794,9 @@ nothing written; pass --write to apply
762
794
  ```
763
795
 
764
796
  An incomplete version such as `--host 0.3` is refused before the manifest is
765
- read, and `--range` still wins when both flags are passed.
797
+ read. Passing `--range` beside `--host` is allowed only when that range accepts
798
+ the host; a contradictory pair is refused before the manifest is read, the same
799
+ as in `fix`.
766
800
 
767
801
  Checks that cannot be repaired without guessing — a missing patch file, a root
768
802
  export that points at the CLI, a README with no Requirements section — still
@@ -808,8 +842,11 @@ dsh-plugin fix: wrote engines.dsh ">=0.3.0 <1.0.0" (was missing)
808
842
  /Users/you/my-panel/package.json
809
843
  ```
810
844
 
811
- A host version that is not complete semver is refused, and `--range` still wins
812
- when it is passed beside `--host`.
845
+ A host version that is not complete semver is refused. `--range` wins when it
846
+ is passed beside `--host`, but only when that range accepts the host: a pair
847
+ that disagrees is refused instead of written, because a range that excludes the
848
+ host would leave the install failing. Drop `--range` to let `--host` aim the
849
+ range automatically, or pass a range that includes the host version.
813
850
 
814
851
  For a repository you have not cloned, see
815
852
  [Repair a repository you have not cloned](#repair-a-repository-you-have-not-cloned):
package/lib/audit.mjs CHANGED
@@ -19,7 +19,7 @@ import {
19
19
  stripBom,
20
20
  version as manifestVersion,
21
21
  } from './doctor.mjs';
22
- import { hostCompatibility } from './compat.mjs';
22
+ import { hostCompatibility, hostVersionIssue } from './compat.mjs';
23
23
  import { readGraph } from './dev.mjs';
24
24
  import { auditRemote, fixRemote, parseTarget } from './remote.mjs';
25
25
  import { resolvePath } from './paths.mjs';
@@ -447,13 +447,19 @@ export function remoteFinding(report, host) {
447
447
  finding.rateLimited = true;
448
448
  if (report.rateLimit !== undefined) finding.rateLimit = report.rateLimit;
449
449
  }
450
+ // A row without a manifest was never read: there is no range to compare and
451
+ // no compatibility answer to give. Attaching `unknown` here would fabricate a
452
+ // verdict (and the printed suffix used to claim the repository declared no
453
+ // range) for a repository GitHub never returned.
454
+ if (manifest === null) return finding;
450
455
  return withHostCompatibility(finding, host);
451
456
  }
452
457
 
453
458
  /**
454
459
  * Add the answer to the question the reports ask: will this range install on
455
- * the host the reader is running? The field is only present when `--host`
456
- * names a version, so an audit of the manifest alone keeps its old shape.
460
+ * the host the reader is running? The field is present only when `--host`
461
+ * names a version and the manifest was read, so an audit of the manifest alone
462
+ * keeps its old shape and an unreadable repository does not invent one.
457
463
  */
458
464
  function withHostCompatibility(row, host) {
459
465
  const text = typeof host === 'string' ? host.trim() : '';
@@ -527,6 +533,14 @@ export async function auditRemoteTargets(
527
533
  } = {},
528
534
  ) {
529
535
  const hostVersion = typeof host === 'string' ? host.trim() : '';
536
+ // Validate before reading the list file or GitHub: a batch caller gets the
537
+ // same refusal as `audit --remote <owner/repo> --host`, and an invalid value
538
+ // can never fan out into one `unknown` verdict per repository. A blank or
539
+ // non-string host is invalid too; only an omitted host means "no answer".
540
+ if (host !== undefined && host !== null) {
541
+ const hostIssue = hostVersionIssue(host);
542
+ if (hostIssue !== null) throw new Error(hostIssue);
543
+ }
530
544
  let targets;
531
545
  if (from !== undefined && from !== null) {
532
546
  targets = await readRemoteTargets({ from, stdin });
@@ -579,7 +593,8 @@ export async function auditRemoteTargets(
579
593
  };
580
594
  return {
581
595
  target,
582
- row: withHostCompatibility(row, hostVersion),
596
+ // No manifest was read, so the row has no range and no host verdict.
597
+ row,
583
598
  problem: true,
584
599
  unreadable: false,
585
600
  rateLimited: true,
@@ -610,16 +625,15 @@ export async function auditRemoteTargets(
610
625
  unreadable = row.unreadable === true;
611
626
  problem = rateLimited || unreadable || row.failures.length > 0 || row.compatibility === 'incompatible';
612
627
  } catch (error) {
613
- row = withHostCompatibility(
614
- {
615
- target: targetName(target),
616
- version: null,
617
- hostRange: null,
618
- failures: [{ check: 'target', message: error instanceof Error ? error.message : String(error) }],
619
- notes: [],
620
- },
621
- hostVersion,
622
- );
628
+ // The read never produced a manifest, so there is nothing to compare the
629
+ // host against; keep the failure row free of a fabricated verdict.
630
+ row = {
631
+ target: targetName(target),
632
+ version: null,
633
+ hostRange: null,
634
+ failures: [{ check: 'target', message: error instanceof Error ? error.message : String(error) }],
635
+ notes: [],
636
+ };
623
637
  problem = true;
624
638
  }
625
639
  return { target, row, problem, unreadable, rateLimited, manifestText };
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' },
package/lib/cli.mjs CHANGED
@@ -6,9 +6,9 @@
6
6
  import fs from 'node:fs';
7
7
  import path from 'node:path';
8
8
 
9
- import { parseVersion } from './compat.mjs';
9
+ import { hostVersionIssue } from './compat.mjs';
10
10
  import { doctor } from './doctor.mjs';
11
- import { DEFAULT_ENGINES, doctorFix, fixEngines } from './fix.mjs';
11
+ import { DEFAULT_ENGINES, doctorFix, fixEngines, validateEnginesRequest } from './fix.mjs';
12
12
  import { auditRemote, fixRemote } from './remote.mjs';
13
13
  import { expandHome, resolvePath } from './paths.mjs';
14
14
  import { init } from './init.mjs';
@@ -94,7 +94,7 @@ Flags
94
94
  --fix with doctor: print the repair plan; write it only with --write
95
95
  --engines with fix: repair the host range in package.json
96
96
  --write with fix: write the change instead of only printing it
97
- --range <range> with fix or doctor --fix: the range to write, default ${DEFAULT_ENGINES}
97
+ --range <range> with fix or doctor --fix: the range to write, default ${DEFAULT_ENGINES}; it must accept --host when both are passed
98
98
  --patch <file> with fix --remote: write the diff to <file>, creating parent directories
99
99
  --log <file> with explain: read a log and find its last known failure
100
100
  --remote <list> with doctor: one owner/repo; with fix: one owner/repo, read-only on GitHub; with audit: owner/repo,owner/repo
@@ -369,19 +369,34 @@ export async function run(argv, io = console, deps = {}) {
369
369
  return 2;
370
370
  }
371
371
 
372
+ // Identify a remote audit here, before any command resolves a target or
373
+ // opens a file, so the host contract can stop it at the same point whether
374
+ // the target came from the command line or from a `--from` list.
375
+ const remoteAuditForm =
376
+ command === 'audit' &&
377
+ (options.remote !== undefined || options.from !== undefined || options.patchDir !== undefined);
378
+
372
379
  // `--host` means a URL for a local audit and a DSH version for a remote one,
373
380
  // so a bare flag must stop before either reads anything. Otherwise the audit
374
381
  // silently omits the compatibility answer the user asked for.
375
382
  if (options.hostMissing === true || (options.host !== undefined && String(options.host).trim() === '')) {
376
- const hint =
377
- command === 'audit'
378
- ? 'the running app URL, or the DSH version with --remote'
379
- : command === 'fix'
380
- ? 'the DSH version to aim at'
381
- : command === 'dev'
382
- ? 'the app URL'
383
- : 'a value';
384
- io.error(`dsh-plugin ${command} --host needs ${hint}`);
383
+ if (remoteAuditForm === true && options.host !== undefined) {
384
+ // A blank value is not the same as a missing flag: it was supplied, but
385
+ // it cannot name a DSH version. Report it through the same sentence the
386
+ // remote audit and its library entry points use, so the single-target
387
+ // and batch forms never disagree about what a valid host is.
388
+ io.error(`dsh-plugin audit --remote ${hostVersionIssue(options.host)}`);
389
+ } else {
390
+ const hint =
391
+ command === 'audit'
392
+ ? 'the running app URL, or the DSH version with --remote'
393
+ : command === 'fix'
394
+ ? 'the DSH version to aim at'
395
+ : command === 'dev'
396
+ ? 'the app URL'
397
+ : 'a value';
398
+ io.error(`dsh-plugin ${command} --host needs ${hint}`);
399
+ }
385
400
  return 2;
386
401
  }
387
402
 
@@ -504,8 +519,20 @@ export async function run(argv, io = console, deps = {}) {
504
519
  io.error('dsh-plugin fix --remote --patch needs a file path, for example: --patch repair.patch');
505
520
  return 2;
506
521
  }
522
+ // Validate the range/host pair before the --write refusal. Both are
523
+ // usage errors, but a typo in --host is the one the author can act on;
524
+ // "remote repositories are read-only" for `--host banana --write` named
525
+ // the wrong flag and hid the value that needs fixing. This runs before
526
+ // any GitHub read, like the same check inside fixRemote().
527
+ const requested = validateEnginesRequest({ range: options.range, host: options.host });
528
+ if (requested.ok !== true) {
529
+ io.error(`dsh-plugin fix --remote: ${requested.failures[0].message}`);
530
+ return 2;
531
+ }
507
532
  if (options.write === true) {
508
- io.error('dsh-plugin fix --remote: remote repositories are read-only; apply the diff in a checkout');
533
+ io.error(
534
+ 'dsh-plugin fix --remote: remote repositories are read-only; pass --patch <file> to save the diff, then apply it with git apply in your checkout (or run fix . --engines --write there)',
535
+ );
509
536
  return 2;
510
537
  }
511
538
  let result;
@@ -713,8 +740,22 @@ export async function run(argv, io = console, deps = {}) {
713
740
  io.error('dsh-plugin audit --home needs a directory path');
714
741
  return 2;
715
742
  }
743
+ // A remote `--host` is a complete DSH version, not a range or a label.
744
+ // Without this check a typo compared every repository against a version
745
+ // the parser cannot read, answered `unknown`, and could still exit 0 with
746
+ // a clean-looking report. Validate it before even importing the scanner,
747
+ // and before resolving the target, the jobs, or a list file: the
748
+ // single-target and batch forms stop at the same point, and neither has
749
+ // touched GitHub or the filesystem.
750
+ if (remoteAuditForm === true && options.host !== undefined) {
751
+ const hostIssue = hostVersionIssue(options.host);
752
+ if (hostIssue !== null) {
753
+ io.error(`dsh-plugin audit --remote ${hostIssue}`);
754
+ return 2;
755
+ }
756
+ }
716
757
  const { audit, parseJobs } = await import('./audit.mjs');
717
- if (options.remote !== undefined || options.from !== undefined || options.patchDir !== undefined) {
758
+ if (remoteAuditForm === true) {
718
759
  let remote = remoteTarget(options);
719
760
  let from = options.from;
720
761
  let jobs;
@@ -724,16 +765,6 @@ export async function run(argv, io = console, deps = {}) {
724
765
  io.error(`dsh-plugin audit --jobs: ${error instanceof Error ? error.message : String(error)}`);
725
766
  return 2;
726
767
  }
727
- // A remote `--host` is a complete DSH version, not a range or a label.
728
- // Without this check a typo compared every repository against a version
729
- // the parser cannot read, answered `unknown`, and could still exit 0 with
730
- // a clean-looking report. Stop before reading a list file or GitHub.
731
- if (options.host !== undefined && parseVersion(options.host) === null) {
732
- io.error(
733
- `dsh-plugin audit --remote --host needs a complete DSH version such as 0.2.2, got ${JSON.stringify(options.host)}`,
734
- );
735
- return 2;
736
- }
737
768
  if (from !== undefined && String(from).trim() === '') {
738
769
  io.error('dsh-plugin audit --remote --from needs a file path, or - to read the list from standard input');
739
770
  return 2;
package/lib/compat.mjs CHANGED
@@ -46,6 +46,20 @@ export function parseVersion(value) {
46
46
  };
47
47
  }
48
48
 
49
+ /**
50
+ * The audit's `--host` contract, in one place: a complete version to compare
51
+ * against, never a range, a partial version or a label. Returns null when the
52
+ * value is valid, or the sentence the CLI and the library report. Without the
53
+ * shared check the CLI rejects `banana` while a caller of `auditRemote()` or
54
+ * `auditRemoteTargets()` still gets a fabricated `unknown` answer after a
55
+ * GitHub read.
56
+ */
57
+ export function hostVersionIssue(value) {
58
+ if (typeof value === 'string' && parseVersion(value) !== null) return null;
59
+ const got = typeof value === 'string' ? JSON.stringify(value) : String(value);
60
+ return `--host needs a complete DSH version such as 0.2.2, got ${got}`;
61
+ }
62
+
49
63
  function partialNumber(value) {
50
64
  if (value === undefined || value === null || value === '' || /^[xX*]$/u.test(value) === true) return null;
51
65
  if (/^\d+$/u.test(value) === false) return undefined;
package/lib/fix.mjs CHANGED
@@ -26,9 +26,11 @@ export const DEFAULT_ENGINES = '>=0.2.0';
26
26
  * Turn `--range` and `--host` into the range a repair should propose.
27
27
  *
28
28
  * `--host` is the compatibility path: no hand-written range, just the version
29
- * the install rejected. `--range` still wins when both are passed, but the
30
- * host is kept so the caller can explain whether that explicit range includes
31
- * it. Without either flag the long-standing default is unchanged.
29
+ * the install rejected. `--range` wins when both are passed and it accepts the
30
+ * host; a pair that disagrees is refused. Writing an explicit range that
31
+ * excludes the host would repeat the install failure the command exists to
32
+ * repair — the old planner printed that mismatch as a note and wrote the
33
+ * unusable range anyway. Without either flag the default is unchanged.
32
34
  */
33
35
  export function resolveEnginesRange({ range, host } = {}) {
34
36
  const hasRange = range !== undefined && range !== null;
@@ -54,6 +56,21 @@ export function resolveEnginesRange({ range, host } = {}) {
54
56
  let why = plan?.why ?? null;
55
57
  if (plan !== null && proposed !== plan.range) {
56
58
  const includes = satisfiesRange(proposed, plan.host);
59
+ if (includes === false && isHostRange(proposed) === true) {
60
+ // A valid explicit range that excludes the host cannot repair the
61
+ // install. The host was named to say which version has to work, so the
62
+ // two flags disagree and there is no safe edit to make.
63
+ const stableHost = plan.host.split('-')[0];
64
+ const prereleaseOnly =
65
+ plan.host.includes('-') === true && satisfiesRange(proposed, stableHost) === true;
66
+ const detail =
67
+ prereleaseOnly === true
68
+ ? `; npm's pre-release rule only lets a range accept ${plan.host} when the range names that pre-release`
69
+ : '';
70
+ return {
71
+ error: `--range "${proposed}" does not include host ${plan.host}, so it would not repair the install${detail}; pass a range that accepts ${plan.host}, or drop --range to aim at the host automatically`,
72
+ };
73
+ }
57
74
  why =
58
75
  includes === true
59
76
  ? `host ${plan.host} is inside the explicit range "${proposed}"`
package/lib/remote.mjs CHANGED
@@ -17,6 +17,7 @@ import fs from 'node:fs';
17
17
  import path from 'node:path';
18
18
 
19
19
  import { expandHome } from './paths.mjs';
20
+ import { hostVersionIssue } from './compat.mjs';
20
21
  import {
21
22
  checkDshField,
22
23
  checkFilesList,
@@ -248,12 +249,23 @@ export async function auditRemote(
248
249
  const parsed = parseTarget(target);
249
250
  const { owner, repo, slug } = parsed;
250
251
  const hostVersion = typeof host === 'string' ? host.trim() : '';
252
+ // The CLI validates `--host`, but this entry point is exported and the batch
253
+ // audit calls it too. Refuse a value that cannot be compared before the
254
+ // GitHub read, so no caller can turn a typo into `unknown` after paying for
255
+ // a request. Only an omitted host means "no compatibility answer".
256
+ if (host !== undefined && host !== null) {
257
+ const hostIssue = hostVersionIssue(host);
258
+ if (hostIssue !== null) throw new Error(hostIssue);
259
+ }
251
260
  const withHost = (report) => {
252
- if (hostVersion === '') return report;
261
+ // Only a read manifest can answer the question. An unreadable repository
262
+ // has no range, so the report stays byte-for-byte what it was without
263
+ // `--host` instead of carrying `unknown` beside a range it never saw.
264
+ if (hostVersion === '' || report.manifest === null) return report;
253
265
  return {
254
266
  ...report,
255
267
  host: hostVersion,
256
- compatibility: report.manifest === null ? 'unknown' : checkHostCompatibility(report.manifest, hostVersion),
268
+ compatibility: checkHostCompatibility(report.manifest, hostVersion),
257
269
  };
258
270
  };
259
271
  const failures = [];
@@ -388,8 +400,17 @@ export async function auditRemote(
388
400
  // tarball will contain: `lib/` is output, not source. Asking GitHub whether
389
401
  // those paths exist would call a working plugin broken, so the file-level
390
402
  // checks are reported as skipped instead of failed.
391
- const BUILD_HOOKS = ['prepack', 'prepublishOnly', 'prepare', 'build'];
392
- 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
+ });
393
414
  const built = builds.length > 0;
394
415
 
395
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.34",
3
+ "version": "0.20.36",
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": {
@@ -11,6 +11,10 @@
11
11
  * not from a hand-written example or a library-only shortcut.
12
12
  *
13
13
  * Run: node scripts/compatibility-sample.mjs
14
+ * node scripts/compatibility-sample.mjs --json
15
+ *
16
+ * `--json` replays the same command with the flag CI reads, so the machine
17
+ * form is checked against the executable too, not just described in prose.
14
18
  */
15
19
  import { spawnSync } from 'node:child_process';
16
20
  import fs from 'node:fs';
@@ -24,6 +28,13 @@ const SAMPLE = path.join(ROOT, 'examples', 'compatibility-sample');
24
28
  const BIN = path.join(ROOT, 'bin', 'dsh-plugin.mjs');
25
29
  const TARGET = 'L3n3L/dsh-resume';
26
30
  const HOST = '0.2.2-alpha.3';
31
+ const JSON_OUTPUT = process.argv.includes('--json');
32
+
33
+ const unknown = process.argv.slice(2).filter((argument) => argument !== '--json');
34
+ if (unknown.length > 0) {
35
+ process.stderr.write(`compatibility-sample: unknown argument ${unknown.join(' ')}; use --json for the machine form\n`);
36
+ process.exit(2);
37
+ }
27
38
 
28
39
  // A CommonJS preload works on every Node version the package supports; an
29
40
  // `--import` hook would require a newer Node than `engines` promises.
@@ -63,19 +74,17 @@ function replay() {
63
74
  const preload = path.join(scratch, 'github-preload.cjs');
64
75
  try {
65
76
  fs.writeFileSync(preload, PRELOAD);
66
- const result = spawnSync(
67
- process.execPath,
68
- ['--require', preload, BIN, 'audit', '--remote', TARGET, '--host', HOST],
69
- {
70
- cwd: ROOT,
71
- encoding: 'utf8',
72
- env: {
73
- ...process.env,
74
- DSH_COMPATIBILITY_SAMPLE: SAMPLE,
75
- DSH_COMPATIBILITY_TARGET: TARGET,
76
- },
77
+ const command = ['--require', preload, BIN, 'audit', '--remote', TARGET, '--host', HOST];
78
+ if (JSON_OUTPUT === true) command.push('--json');
79
+ const result = spawnSync(process.execPath, command, {
80
+ cwd: ROOT,
81
+ encoding: 'utf8',
82
+ env: {
83
+ ...process.env,
84
+ DSH_COMPATIBILITY_SAMPLE: SAMPLE,
85
+ DSH_COMPATIBILITY_TARGET: TARGET,
77
86
  },
78
- );
87
+ });
79
88
  if (result.error !== undefined) throw result.error;
80
89
  const stderr = String(result.stderr ?? '').trim();
81
90
  if (result.status !== 1) {