dsh-plugin-toolkit 0.20.34 → 0.20.35

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,68 @@
1
+ ## 0.20.35
2
+
3
+ - **The compatibility answer now has a reproducible machine-readable form.**
4
+ The README's "Will this plugin install on my DSH?" section already showed
5
+ the real `audit --remote --host` output for `L3n3L/dsh-resume@0.1.3` from the
6
+ checked-in snapshot; it now also shows
7
+ `node scripts/compatibility-sample.mjs --json`. `scripts/compatibility-sample.mjs`
8
+ gains the `--json` form of the same replay, so both the human line and the CI
9
+ object come from the shipped executable. The section spells out that an
10
+ incompatible range is reported through `compatibility` (and the exit code)
11
+ rather than an extra `failures` entry, so a consumer that counts only
12
+ `failures.length` cannot mistake a host mismatch for a clean object.
13
+ `test/readme-compatibility.test.mjs` compares both documentation blocks with
14
+ the script's output and pins the JSON shape.
15
+
16
+ - **A blank remote `--host` gets the same refusal as any other invalid
17
+ version.** `audit --remote owner/repo --host ' '` and the batch form used
18
+ to fall through the generic "running app URL" hint because the value was
19
+ empty, while the exported audit functions reported the complete-version
20
+ sentence. The CLI now identifies the remote form before it resolves the
21
+ target, the jobs or a list file, and routes blank and whitespace values
22
+ through `hostVersionIssue()`; the host check also runs before `--jobs`
23
+ parsing. The single-target and `--from` forms are pinned with their
24
+ valid-host controls in `test/audit-remote-host-invalid.test.mjs`: the
25
+ real-list invalid case, the shared blank message, the shipped batch exit
26
+ code, and the `compatible` control.
27
+
28
+ - **A host-aimed repair can no longer write a range that excludes the host.**
29
+ `fix --engines --host 0.3.0 --range ">=0.5.0"` printed `host 0.3.0 is not
30
+ inside the explicit range`, then wrote `>=0.5.0` and exited `0` — the same
31
+ install failure if it was applied. The local fixer, `doctor --fix` and
32
+ `fix --remote` now share the same decision: an explicit `--range` wins only
33
+ when it accepts the named host, and a contradictory pair is a usage error
34
+ before anything is written or any GitHub request is made. The message names
35
+ both values, explains npm's pre-release rule when that is the only reason the
36
+ host is excluded, and points at dropping `--range` to aim the range
37
+ automatically. `fix --remote --host banana --write` also names the bad host
38
+ instead of the read-only refusal, and that refusal now names `--patch` as the
39
+ way to save the repair for a checkout. `test/fix-host-conflict.test.mjs`
40
+ pins the local, `doctor --fix` and remote paths, the accepting-range control,
41
+ and re-applies a remote patch to assert the written range accepts `0.3.0` and
42
+ rejects `1.0.0`.
43
+
44
+ - **The remote audit refuses an invalid `--host` before any read, whichever
45
+ entry point is used.** The CLI already stopped `--host banana` with exit `2`,
46
+ but `auditRemote()` and `auditRemoteTargets()` — the single-target and batch
47
+ paths the command delegates to — still accepted it, read GitHub and answered
48
+ `compatibility: "unknown"`. All three now share `hostVersionIssue()`, so a
49
+ value that is not a complete DSH version is rejected before the repository or
50
+ a `--from` list is read. The acceptance case
51
+ (`audit --remote acme/clean --host banana --json`) is pinned: exit `2`, the
52
+ message names `--host` and `banana`, stdout stays empty and the mocked fetch
53
+ is never called; `--host 0.2.0` still exits `0` with `compatible`. The
54
+ regression test covers the CLI, both exported fan-out functions and a batch
55
+ whose list file must not be opened.
56
+
57
+ - **`audit --remote --host` no longer claims a range it never read.** A
58
+ repository GitHub answered with a 500 or skipped after a rate limit was
59
+ printed as `unknown with dsh <version>; declares no engines.dsh range`, even
60
+ though `package.json` was never read. The host fields are now attached only
61
+ when a manifest exists, so unreadable and rate-limited rows keep their own
62
+ verdict without a fabricated range or compatibility answer. The regression
63
+ test pins the unreadable row, the skipped batch row and a readable control
64
+ that still gets `compatible`.
65
+
1
66
  ## 0.20.34
2
67
 
3
68
  - **`audit --remote` names every finding the same way and never reads a
package/README.md CHANGED
@@ -501,6 +501,31 @@ sample audits the repository's current default branch instead; a README or
501
501
  manifest change since 0.1.3 can add another `readme` or manifest failure to the
502
502
  same row.
503
503
 
504
+ CI should read the same answer as data. This is the reproducible sample again,
505
+ with the flag that changes the form rather than the verdict:
506
+
507
+ ```sh
508
+ $ node scripts/compatibility-sample.mjs --json
509
+ [
510
+ {
511
+ "target": "L3n3L/dsh-resume",
512
+ "version": "0.1.3",
513
+ "hostRange": ">=0.1.0-rc.6 <0.2.0-0",
514
+ "failures": [],
515
+ "notes": [],
516
+ "host": "0.2.2-alpha.3",
517
+ "compatibility": "incompatible"
518
+ }
519
+ ]
520
+ ```
521
+
522
+ `compatibility` is the finding for an incompatible range; the object does not
523
+ invent a second entry in `failures` for the same fact. Gate on `compatibility`
524
+ or the process exit code, not on `failures.length` alone, or a host mismatch
525
+ will look clean. The command still exits `1`, and the test suite compares this
526
+ block with the JSON the executable prints, so the documented shape cannot drift
527
+ from the code that emits it.
528
+
504
529
  The line carries the range `package.json` declares and one of `compatible`,
505
530
  `incompatible`, or `unknown` against that host version. `unknown` is the honest
506
531
  answer for a missing or malformed range — there is nothing to compare — while a
@@ -525,12 +550,16 @@ A bare `--host` is a usage error, not an audit without the comparison: the
525
550
  command exits `2` before it reads GitHub, and `--host --json` does not consume
526
551
  the `--json` flag as a version. The value itself must be a complete version
527
552
  (`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.
553
+ (`0.2`), a tag name, or a blank value is rejected with exit `2` before any
554
+ repository is read or the `--from` list is opened, so a typo cannot turn into a
555
+ clean-looking `unknown` row. The single-target and batch forms use the same
556
+ check and the same message.
530
557
 
531
558
  `--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`.
559
+ is the DSH version to compare against. With `--json`, each finding whose
560
+ manifest was read gains `host` and `compatibility` beside `hostRange`; an
561
+ unreadable or rate-limited repository has no manifest to compare, so it keeps
562
+ its own verdict and does not invent a range or an `unknown` answer.
534
563
 
535
564
  Each repository gets one line with its verdict — `clean`, `failing`,
536
565
  `unreadable`, or `rate-limited` — and the run ends with a counted summary:
@@ -628,11 +657,11 @@ $ dsh-plugin audit --remote --from repos.txt --json
628
657
  Every repository produces one object with `target`, `version`, `hostRange`,
629
658
  `failures` (`{ check, message }`) and `notes`, and the command exits `1` when any
630
659
  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
660
+ `host` and `compatibility` once its manifest was read. A rate-limited
661
+ repository adds `rateLimited: true` and a `rateLimit` object with the HTTP
662
+ `status` and, when GitHub sent one, `resetAt`; it is not marked `unreadable`. A
663
+ network error is printed in `notes` and still exits `1`: a repository the tool
664
+ could not read is never reported as clean. Packages that build before they pack
636
665
  keep their file-level checks in `notes` as before.
637
666
 
638
667
  When the list is a repair queue rather than a report, add `--patch-dir`:
@@ -762,7 +791,9 @@ nothing written; pass --write to apply
762
791
  ```
763
792
 
764
793
  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.
794
+ read. Passing `--range` beside `--host` is allowed only when that range accepts
795
+ the host; a contradictory pair is refused before the manifest is read, the same
796
+ as in `fix`.
766
797
 
767
798
  Checks that cannot be repaired without guessing — a missing patch file, a root
768
799
  export that points at the CLI, a README with no Requirements section — still
@@ -808,8 +839,11 @@ dsh-plugin fix: wrote engines.dsh ">=0.3.0 <1.0.0" (was missing)
808
839
  /Users/you/my-panel/package.json
809
840
  ```
810
841
 
811
- A host version that is not complete semver is refused, and `--range` still wins
812
- when it is passed beside `--host`.
842
+ A host version that is not complete semver is refused. `--range` wins when it
843
+ is passed beside `--host`, but only when that range accepts the host: a pair
844
+ that disagrees is refused instead of written, because a range that excludes the
845
+ host would leave the install failing. Drop `--range` to let `--host` aim the
846
+ range automatically, or pass a range that includes the host version.
813
847
 
814
848
  For a repository you have not cloned, see
815
849
  [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/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 = [];
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.35",
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) {