dsh-plugin-toolkit 0.20.33 → 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,108 @@
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
+
66
+ ## 0.20.34
67
+
68
+ - **`audit --remote` names every finding the same way and never reads a
69
+ failed request as clean.** A batch given GitHub URLs reported the rows it had
70
+ read as `owner/repo` but kept the URL for rows skipped after a rate limit, so
71
+ a consumer joining findings saw two shapes for one list. Every target is now
72
+ normalised through the same parser. A read that fails for a reason other than
73
+ the quota (an HTTP 500 or a network error) is reported as `unreadable` with
74
+ the reason in `notes` and still exits `1`, so an empty `failures` array is
75
+ never mistaken for a pass. A local folder that happens to be named
76
+ `owner/repo` no longer hides the remote target. `test/audit-batch.test.mjs`,
77
+ `test/audit-rate-limit.test.mjs` and `test/remote.test.mjs` cover the
78
+ unreadable row, URL normalisation and the folder-name collision, and the
79
+ README's `--json` example is fenced as JSON so it renders as a code block.
80
+ - **`fix <owner>/<repo> --remote` exits `1` when there is nothing to apply.**
81
+ The command is a repair planner, so exit `0` now means it printed a unified
82
+ diff the author can apply. A manifest that already declares a valid
83
+ `engines.dsh` still prints `ok engines.dsh is already "<range>"; nothing to
84
+ apply` and writes no diff or patch file, but the plan is empty and the exit
85
+ code says so. This makes the remote repair usable in a shell loop that has to
86
+ tell a printed repair from an already-clean repository. The process-boundary
87
+ test now asserts both outcomes, and the README and `docs/repair.md` describe
88
+ the same contract.
89
+ - **`doctor --fix --host` aims the repaired `engines.dsh` at the DSH that
90
+ rejected the install.** The repair planner already accepted a host, but the
91
+ CLI never passed `--host` through, so `doctor --fix ./my-panel --host 0.3.0`
92
+ silently wrote the default `>=0.2.0` — the same range `fix --engines --host`
93
+ would have replaced. The flag now reaches the planner, the preview prints why
94
+ the next major is excluded, and `--write` applies exactly that range.
95
+ `test/doctor-fix.test.mjs` covers the host-aimed preview, the write and an
96
+ incomplete host version that must stop before reading the manifest.
97
+ - **A `package.json` that is not a JSON object is named instead of crashing.**
98
+ A file holding `null`, a string or an array parses as JSON, but every check
99
+ then read a field off the wrong shape: plain `doctor` died with
100
+ `Cannot read properties of null` and `doctor --fix` repeated that message.
101
+ The shared manifest reader now rejects the shape once with
102
+ `package.json does not hold a JSON object`, so the fixer reports the file the
103
+ same way it reports a parse error. The installed-plugin audit uses the same
104
+ reader and gets the cleaner message without a second code path.
105
+
1
106
  ## 0.20.33
2
107
 
3
108
  - **`fix --remote --patch` keeps a CRLF manifest's line endings in the diff.**
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:
@@ -600,6 +629,8 @@ For a CI job or a repair sweep, add `--json`:
600
629
  ```sh
601
630
  $ dsh-plugin audit --remote --from repos.txt --json
602
631
  ```
632
+
633
+ ```json
603
634
  [
604
635
  {
605
636
  "target": "V1ki/dsh-plugin-subscriptions",
@@ -626,11 +657,11 @@ $ dsh-plugin audit --remote --from repos.txt --json
626
657
  Every repository produces one object with `target`, `version`, `hostRange`,
627
658
  `failures` (`{ check, message }`) and `notes`, and the command exits `1` when any
628
659
  repository has a problem. With `--host <version>` each object also carries
629
- `host` and `compatibility`. A rate-limited repository adds `rateLimited: true`
630
- and a `rateLimit` object with the HTTP `status` and, when GitHub sent one,
631
- `resetAt`; it is not marked `unreadable`. A network error is printed in `notes`
632
- and still exits `1`: a repository the tool could not read is never reported as
633
- 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
634
665
  keep their file-level checks in `notes` as before.
635
666
 
636
667
  When the list is a repair queue rather than a report, add `--patch-dir`:
@@ -746,6 +777,24 @@ and a range that already passes is not touched. `--range <range>` chooses the
746
777
  value used when `engines.dsh` needs repair, and `--dry-run` wins if it is passed
747
778
  alongside `--write`.
748
779
 
780
+ When the failed install names the host version, `--host` aims that repair at
781
+ the DSH that rejected it instead of falling back to the default. It is the same
782
+ decision as `fix --engines --host`, so the preview shows the range and why the
783
+ next major is excluded, and `--write` applies exactly that edit:
784
+
785
+ ```sh
786
+ $ npx dsh-plugin-toolkit@latest doctor --fix ./my-panel --host 0.3.0
787
+ dsh-plugin doctor --fix: 1 failed check(s) in /Users/you/my-panel
788
+ ✗ engines.dsh: package.json — would write engines.dsh ">=0.3.0 <1.0.0" (was missing)
789
+ host 0.3.0 is inside ">=0.3.0 <1.0.0"; 1.0.0 is excluded, so the range includes the host you run and stops before the next major
790
+ nothing written; pass --write to apply
791
+ ```
792
+
793
+ An incomplete version such as `--host 0.3` is refused before the manifest is
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`.
797
+
749
798
  Checks that cannot be repaired without guessing — a missing patch file, a root
750
799
  export that points at the CLI, a README with no Requirements section — still
751
800
  appear in the plan with `manual:`, so the command never invents file contents.
@@ -790,8 +839,11 @@ dsh-plugin fix: wrote engines.dsh ">=0.3.0 <1.0.0" (was missing)
790
839
  /Users/you/my-panel/package.json
791
840
  ```
792
841
 
793
- A host version that is not complete semver is refused, and `--range` still wins
794
- 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.
795
847
 
796
848
  For a repository you have not cloned, see
797
849
  [Repair a repository you have not cloned](#repair-a-repository-you-have-not-cloned):
@@ -838,8 +890,8 @@ dsh-plugin fix: would write engines.dsh ">=0.2.0" (was missing) in PrismLean/dsh
838
890
 
839
891
  When `package.json` already declares a range that clears the check, there is
840
892
  nothing to apply: the command prints `ok engines.dsh is already "<range>";
841
- nothing to apply` and exits `0`, the same no-op as `fix --engines` on a
842
- checkout. No diff and no patch file is written.
893
+ nothing to apply`, exits `1`, and writes no diff or patch file. Exit `0` means a
894
+ repair was printed for the author; `1` means there was no repair to print.
843
895
 
844
896
  To apply it, clone the repository, save that diff with `--patch`, and apply it
845
897
  in the checkout:
@@ -1073,8 +1125,8 @@ merged
1073
1125
 
1074
1126
  | Code | Meaning |
1075
1127
  | --- | --- |
1076
- | 0 | Done, or nothing to complain about — including `fix --remote` when `engines.dsh` is already a valid range |
1077
- | 1 | A check failed, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
1128
+ | 0 | Done, or nothing to complain about |
1129
+ | 1 | A check failed, a remote `fix` found nothing to apply, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
1078
1130
  | 2 | Unknown command, invalid usage, or a remote request that could not be completed |
1079
1131
 
1080
1132
  A flag that takes a value must be given one. When `--range`, `--log`,
@@ -1085,9 +1137,9 @@ is the last token, or is followed by another flag, the command exits `2` and
1085
1137
  names the flag instead of falling back to a default or consuming the next
1086
1138
  option as the value.
1087
1139
 
1088
- `fix <owner>/<repo> --remote` exits `0` both when it prints a diff for a missing
1089
- `engines.dsh` and when the manifest already declares a range that clears the
1090
- check; the second case prints `ok ... nothing to apply` and writes no diff.
1140
+ `fix <owner>/<repo> --remote` exits `0` when it prints a diff for a missing
1141
+ `engines.dsh`; when the manifest already declares a range that clears the check,
1142
+ the second case prints `ok ... nothing to apply`, writes no diff and exits `1`.
1091
1143
 
1092
1144
  ## What is not here yet
1093
1145
 
package/lib/audit.mjs CHANGED
@@ -19,9 +19,9 @@ 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
- import { auditRemote, fixRemote } from './remote.mjs';
24
+ import { auditRemote, fixRemote, parseTarget } from './remote.mjs';
25
25
  import { resolvePath } from './paths.mjs';
26
26
 
27
27
  export { hostCompatibility } from './compat.mjs';
@@ -395,6 +395,25 @@ export function patchFileName(target) {
395
395
  return `${parts[1]}__${parts[2]}.patch`;
396
396
  }
397
397
 
398
+ /**
399
+ * The name a finding reports for a target. A readable row carries the parsed
400
+ * slug already, but a row that was skipped after a rate limit or refused before
401
+ * the read has only the input string. Normalise that string through the same
402
+ * parser the read would use, so a list of GitHub URLs produces `owner/repo` for
403
+ * every row and a consumer can join the findings without rewriting targets.
404
+ * An invalid entry keeps the text the caller wrote; the failure row for it
405
+ * already says what was wrong.
406
+ */
407
+ function targetName(value) {
408
+ if (value !== null && typeof value === 'object' && typeof value.slug === 'string') return value.slug;
409
+ if (typeof value !== 'string') return String(value ?? '');
410
+ try {
411
+ return parseTarget(value).slug;
412
+ } catch {
413
+ return value;
414
+ }
415
+ }
416
+
398
417
  function noteMessages(report) {
399
418
  if (Array.isArray(report?.notes)) return report.notes;
400
419
  const messages = report?.notes?.messages;
@@ -412,7 +431,7 @@ function noteMessages(report) {
412
431
  export function remoteFinding(report, host) {
413
432
  const manifest = report?.manifest ?? null;
414
433
  const finding = {
415
- target: report?.target?.slug ?? String(report?.target ?? ''),
434
+ target: targetName(report?.target),
416
435
  version: manifest === null ? null : manifestVersion(manifest),
417
436
  hostRange: manifest === null ? null : hostRange(manifest),
418
437
  failures: (report?.failures ?? []).map((failure) => ({
@@ -428,13 +447,19 @@ export function remoteFinding(report, host) {
428
447
  finding.rateLimited = true;
429
448
  if (report.rateLimit !== undefined) finding.rateLimit = report.rateLimit;
430
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;
431
455
  return withHostCompatibility(finding, host);
432
456
  }
433
457
 
434
458
  /**
435
459
  * Add the answer to the question the reports ask: will this range install on
436
- * the host the reader is running? The field is only present when `--host`
437
- * 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.
438
463
  */
439
464
  function withHostCompatibility(row, host) {
440
465
  const text = typeof host === 'string' ? host.trim() : '';
@@ -508,6 +533,14 @@ export async function auditRemoteTargets(
508
533
  } = {},
509
534
  ) {
510
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
+ }
511
544
  let targets;
512
545
  if (from !== undefined && from !== null) {
513
546
  targets = await readRemoteTargets({ from, stdin });
@@ -546,7 +579,7 @@ export async function auditRemoteTargets(
546
579
  const skipped = (target) => {
547
580
  const reset = rateLimitState.info?.resetAt;
548
581
  const row = {
549
- target: String(target),
582
+ target: targetName(target),
550
583
  version: null,
551
584
  hostRange: null,
552
585
  failures: [],
@@ -560,7 +593,8 @@ export async function auditRemoteTargets(
560
593
  };
561
594
  return {
562
595
  target,
563
- row: withHostCompatibility(row, hostVersion),
596
+ // No manifest was read, so the row has no range and no host verdict.
597
+ row,
564
598
  problem: true,
565
599
  unreadable: false,
566
600
  rateLimited: true,
@@ -591,16 +625,15 @@ export async function auditRemoteTargets(
591
625
  unreadable = row.unreadable === true;
592
626
  problem = rateLimited || unreadable || row.failures.length > 0 || row.compatibility === 'incompatible';
593
627
  } catch (error) {
594
- row = withHostCompatibility(
595
- {
596
- target: String(target),
597
- version: null,
598
- hostRange: null,
599
- failures: [{ check: 'target', message: error instanceof Error ? error.message : String(error) }],
600
- notes: [],
601
- },
602
- hostVersion,
603
- );
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
+ };
604
637
  problem = true;
605
638
  }
606
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';
@@ -30,6 +30,7 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
30
30
 
31
31
  dsh-plugin doctor --fix [dir] print the repair plan; write it only with --write
32
32
  dsh-plugin doctor --fix ./my-panel --write
33
+ dsh-plugin doctor --fix ./my-panel --host 0.3.0 aim the range at the DSH that rejected it
33
34
 
34
35
  dsh-plugin fix <dir> --engines print the host range doctor asks for; write it only with --write
35
36
  dsh-plugin fix ./my-panel --engines --write
@@ -93,14 +94,14 @@ Flags
93
94
  --fix with doctor: print the repair plan; write it only with --write
94
95
  --engines with fix: repair the host range in package.json
95
96
  --write with fix: write the change instead of only printing it
96
- --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
97
98
  --patch <file> with fix --remote: write the diff to <file>, creating parent directories
98
99
  --log <file> with explain: read a log and find its last known failure
99
100
  --remote <list> with doctor: one owner/repo; with fix: one owner/repo, read-only on GitHub; with audit: owner/repo,owner/repo
100
101
  --from <file> with audit --remote: read owner/repo entries from <file>, one per line; - means standard input
101
102
  --jobs <n> with audit --remote: read n repositories at once, default 4, capped at 8
102
103
  --patch-dir <dir> with audit --remote: write one .patch per repository that needs a repair
103
- --host <value> with audit: the running app URL; with audit --remote or fix: the complete DSH version to compare against or aim at
104
+ --host <value> with audit: the running app URL; with audit --remote or fix (including doctor --fix): the complete DSH version to compare against or aim at
104
105
  --json with audit --remote: print the findings as JSON, one object per repository
105
106
  --index <path> index file, default market/index.json
106
107
  --market <dir> with release: a checkout of the repository that holds the index
@@ -368,19 +369,34 @@ export async function run(argv, io = console, deps = {}) {
368
369
  return 2;
369
370
  }
370
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
+
371
379
  // `--host` means a URL for a local audit and a DSH version for a remote one,
372
380
  // so a bare flag must stop before either reads anything. Otherwise the audit
373
381
  // silently omits the compatibility answer the user asked for.
374
382
  if (options.hostMissing === true || (options.host !== undefined && String(options.host).trim() === '')) {
375
- const hint =
376
- command === 'audit'
377
- ? 'the running app URL, or the DSH version with --remote'
378
- : command === 'fix'
379
- ? 'the DSH version to aim at'
380
- : command === 'dev'
381
- ? 'the app URL'
382
- : 'a value';
383
- 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
+ }
384
400
  return 2;
385
401
  }
386
402
 
@@ -420,6 +436,10 @@ export async function run(argv, io = console, deps = {}) {
420
436
  result = doctorFix({
421
437
  dir,
422
438
  range: options.range,
439
+ // The failed install usually names the DSH version; aiming the repair
440
+ // at it is the same decision `fix --engines --host` makes, so one range
441
+ // is written whichever repair command the author reaches for.
442
+ host: options.host,
423
443
  // A dry run is the default, and --dry-run wins if somebody passes both.
424
444
  write: options.write === true,
425
445
  dryRun: options.dryRun === true,
@@ -448,6 +468,10 @@ export async function run(argv, io = console, deps = {}) {
448
468
  io.log(` ✗ ${entry.check}: ${entry.path} — manual: ${entry.manual}`);
449
469
  }
450
470
  }
471
+ // A range aimed at a named host is a decision, not just a string: show the
472
+ // sentence `fix --engines --host` already prints so the author can see why
473
+ // the next major is excluded.
474
+ if (typeof result.why === 'string' && result.why.length > 0) io.log(` ${result.why}`);
451
475
 
452
476
  if (result.written === true) {
453
477
  for (const entry of result.edits) {
@@ -495,8 +519,20 @@ export async function run(argv, io = console, deps = {}) {
495
519
  io.error('dsh-plugin fix --remote --patch needs a file path, for example: --patch repair.patch');
496
520
  return 2;
497
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
+ }
498
532
  if (options.write === true) {
499
- 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
+ );
500
536
  return 2;
501
537
  }
502
538
  let result;
@@ -515,12 +551,14 @@ export async function run(argv, io = console, deps = {}) {
515
551
  return 2;
516
552
  }
517
553
  if (result.changed !== true) {
518
- // A manifest that already declares a range clearing the check is a
519
- // successful repair plan, exactly like the local `fix --engines` no-op:
520
- // there is no failure to report, so the documented exit code is 0.
554
+ // This command exists to produce a repair, so "nothing to apply" is not
555
+ // success: no diff was printed and no patch file was written. Exit 1
556
+ // lets a loop over the ecosystem tell a repair that was handed to the
557
+ // author (0) from a repository that already passes (1) without parsing
558
+ // stdout. The message still names the range, so the reason is visible.
521
559
  io.log(`ok engines.dsh is already "${result.range}"; nothing to apply`);
522
560
  if (typeof result.why === 'string' && result.why.length > 0) io.log(` ${result.why}`);
523
- return 0;
561
+ return 1;
524
562
  }
525
563
  const was = result.before === null ? 'missing' : `"${result.before}"`;
526
564
  io.log(`dsh-plugin fix: would write engines.dsh "${result.range}" (was ${was}) in ${result.target.slug}`);
@@ -702,8 +740,22 @@ export async function run(argv, io = console, deps = {}) {
702
740
  io.error('dsh-plugin audit --home needs a directory path');
703
741
  return 2;
704
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
+ }
705
757
  const { audit, parseJobs } = await import('./audit.mjs');
706
- if (options.remote !== undefined || options.from !== undefined || options.patchDir !== undefined) {
758
+ if (remoteAuditForm === true) {
707
759
  let remote = remoteTarget(options);
708
760
  let from = options.from;
709
761
  let jobs;
@@ -713,16 +765,6 @@ export async function run(argv, io = console, deps = {}) {
713
765
  io.error(`dsh-plugin audit --jobs: ${error instanceof Error ? error.message : String(error)}`);
714
766
  return 2;
715
767
  }
716
- // A remote `--host` is a complete DSH version, not a range or a label.
717
- // Without this check a typo compared every repository against a version
718
- // the parser cannot read, answered `unknown`, and could still exit 0 with
719
- // a clean-looking report. Stop before reading a list file or GitHub.
720
- if (options.host !== undefined && parseVersion(options.host) === null) {
721
- io.error(
722
- `dsh-plugin audit --remote --host needs a complete DSH version such as 0.2.2, got ${JSON.stringify(options.host)}`,
723
- );
724
- return 2;
725
- }
726
768
  if (from !== undefined && String(from).trim() === '') {
727
769
  io.error('dsh-plugin audit --remote --from needs a file path, or - to read the list from standard input');
728
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/doctor.mjs CHANGED
@@ -93,6 +93,14 @@ export function readManifestSource(dir) {
93
93
  } catch (error) {
94
94
  throw new Error(`${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
95
95
  }
96
+ // npm's manifest is an object. A file holding `null`, a string or an array
97
+ // parses as JSON but every check would then read a field off the wrong shape;
98
+ // `doctor` used to fail with a bare `Cannot read properties of null` instead
99
+ // of naming the file. Reject it once here so `doctor`, `doctor --fix` and the
100
+ // installed-plugin audit all report the same actionable sentence.
101
+ if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest) === true) {
102
+ throw new Error(`${manifestPath} does not hold a JSON object`);
103
+ }
96
104
  return { manifest, manifestPath, raw, target };
97
105
  }
98
106
 
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,
@@ -146,12 +147,23 @@ export function tokenOf(env = process.env) {
146
147
  * drift.
147
148
  */
148
149
  export function parseTarget(target) {
150
+ const raw = typeof target === 'string' ? target.trim() : '';
149
151
  const parsed = classifyTarget(target);
150
152
  if (parsed.kind === 'repo') {
151
153
  const { owner, repo } = parsed;
152
154
  return { owner, repo, slug: `${owner}/${repo}` };
153
155
  }
154
156
  if (parsed.kind === 'local') {
157
+ // `classifyTarget` answers "local" for an `owner/repo` string when a folder
158
+ // of that name happens to exist. These commands were told the target is
159
+ // remote, so the syntactic slug wins over the local tree; only a path that
160
+ // cannot be a slug is still refused.
161
+ const slug = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/u.exec(raw);
162
+ if (slug !== null) {
163
+ const owner = slug[1];
164
+ const repo = slug[2].replace(/\.git$/iu, '');
165
+ return { owner, repo, slug: `${owner}/${repo}` };
166
+ }
155
167
  throw new Error(`${JSON.stringify(target)} is a folder on this machine; run \`dsh-plugin doctor ${target}\` instead`);
156
168
  }
157
169
  if (parsed.kind === 'search') {
@@ -237,12 +249,23 @@ export async function auditRemote(
237
249
  const parsed = parseTarget(target);
238
250
  const { owner, repo, slug } = parsed;
239
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
+ }
240
260
  const withHost = (report) => {
241
- 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;
242
265
  return {
243
266
  ...report,
244
267
  host: hostVersion,
245
- compatibility: report.manifest === null ? 'unknown' : checkHostCompatibility(report.manifest, hostVersion),
268
+ compatibility: checkHostCompatibility(report.manifest, hostVersion),
246
269
  };
247
270
  };
248
271
  const failures = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.33",
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) {