dsh-plugin-toolkit 0.20.11 → 0.20.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,86 @@
1
- ## Unreleased
2
-
1
+ ## 0.20.13
2
+
3
+ - **The compatibility sample says which snapshot it answers for.** The README
4
+ now names the eight reports behind "will this plugin install on my DSH?" and
5
+ states that the quoted `incompatible` line comes from the frozen 0.1.3 sample
6
+ under `examples/compatibility-sample/`, not from whatever the upstream
7
+ repository's default branch contains today. The sample README explains why it
8
+ keeps a `## Requirements` heading even though the upstream README is
9
+ localized: it isolates the host-range verdict, while a live audit also runs
10
+ the README check and can add a `readme` failure to the same row.
11
+ - **A leading `~` expands in every user-named path, not just `--log`.** On
12
+ `cmd` and PowerShell the shell leaves the tilde literal, so
13
+ `init '~/my-panel' --name my-panel` used to create a directory literally
14
+ named `~` in the current folder, and `doctor '~/my-panel'` then looked in
15
+ the same wrong place. Both the CLI and the exported `init`/`doctor`/`fix`/
16
+ `verify`/`dev`/`release` functions now expand `~/` and `~\` before any
17
+ filesystem access, as do `--home`, `--market`, `--dest`, `--from`,
18
+ `--patch-dir`, `--patch`, `--log` and `--index`. The scaffold lands in
19
+ `$HOME/my-panel`, `doctor` exits `0` on it, and no literal `~` folder is
20
+ created.
21
+ - **Major-only comparator ranges get npm's boundaries.** `audit --remote
22
+ <owner/repo> --host <version>` filled a missing minor with 0 before deciding
23
+ the edge of `<=1`, `>1` and hyphen ranges such as `1.2.3 - 2`, so it called
24
+ 1.2.3 compatible with `<=1` and incompatible with `>1` — the reverse of what
25
+ the installer does. The same answer is used by `doctor --remote`, `--json`
26
+ and `--patch-dir`. The older `~>` spelling of `~` is now parsed too, instead
27
+ of being reported as unknown. Regression tests pin all four forms against npm
28
+ semver.
29
+ - **`doctor --remote` reads the README the way a checkout does.** A published
30
+ repository whose README has no `## Requirements` heading, or whose
31
+ Requirements section omits the `engines.dsh` range it declares, used to print
32
+ `ok` and exit `0`, while the same checkout failed the `readme` check. The
33
+ remote audit now reports that failure and exits `1`; `audit --remote` shares
34
+ the check, so both the single-repository and `--from` batch forms print the
35
+ `failing` row and carry its `readme` failure in the `--json` finding. A README
36
+ that states the declared range still exits `0`.
37
+ - **`dsh-plugin doctor` checks the package name before it packs anything.** A
38
+ `package.json` whose `name` is missing, empty, or not a valid npm package name
39
+ (for example `My Plugin!`) used to print `ok` and exit `0`, while
40
+ `verify --no-mount` failed later at `npm pack`. The manifest preflight now
41
+ reports a `name:` failure and exits `1`, and the same check reaches
42
+ `doctor --remote` and `audit --remote` through the shared manifest check.
43
+ `init` uses the same validator, so a scaffold's name and the check that blesses
44
+ it stay in step. `npm test` pins the result through the shipped CLI: missing,
45
+ empty and malformed names all exit `1` (`accepted=0/3`), while a valid plain or
46
+ scoped name exits `0`.
47
+ - **`doctor --remote` runs the same `dsh` field check as local `doctor`.** A
48
+ repository whose `package.json` has `dsh: {}` and no `dsh.bundle.patch` used
49
+ to print `ok` and exit `0`, because the remote file checks only looked for a
50
+ patch that was declared. It now reports `dsh field: dsh.bundle is missing` and
51
+ exits `1`; the failure is also carried into `audit --remote`, and a clean
52
+ repository still exits `0`.
53
+ - **`fix --remote` can aim the range at the host that rejected the install.**
54
+ `fix <owner>/<repo> --remote --engines --host 0.3.0 --patch repair.patch`
55
+ plans the same `>=0.3.0 <1.0.0` range that `fix . --engines --host 0.3.0
56
+ --write` writes in a checkout. The remote planner and the local writer share
57
+ one decision, so the patch both accepts the host and rejects the next major,
58
+ prints why, and a non-semver `--host` exits `2` before creating a patch file.
59
+ - **`release` refuses a bad host range instead of throwing at the index step.**
60
+ A malformed `engines.dsh` that reached the market-entry builder used to escape
61
+ as an exception, outside the normal `{ ok: false, stage, failures }` result.
62
+ `release` now reports that problem in the `index` stage and writes nothing; a
63
+ manifest with the same bad range is already stopped by the preflight, so the
64
+ command returns before a tag is created. The regression test checks that the
65
+ index file is byte-for-byte unchanged and that the registry is never called.
66
+
67
+ ## 0.20.12
68
+
69
+ - **`dsh-plugin fix <owner>/<repo> --remote` treats an already-correct range as
70
+ success.** When `package.json` already declares an `engines.dsh` range that
71
+ clears the check, the command still prints `ok engines.dsh is already
72
+ "<range>"; nothing to apply` but now exits `0` instead of `1`, matching the
73
+ local `fix --engines` no-op and the documented exit-code contract. No diff or
74
+ patch file is written.
75
+ - **The remote repair keeps its diff and error paths.** A manifest with no
76
+ `engines.dsh` still prints the unified diff and exits `0`; an invalid target
77
+ and a network or HTTP read failure still exit `2`; and the command writes no
78
+ local file unless `--patch` asks for one. Regression tests pin those paths
79
+ beside the already-correct no-op.
80
+ - **The remote repair exit codes are covered at the process boundary.** `npm
81
+ test` now spawns the real CLI for a remote manifest that is missing
82
+ `engines.dsh` and one that already declares a valid range, asserting exit
83
+ `0` for both. The README Exit codes table states the same contract.
3
84
  - **A malformed `package.json` in an ordinary dependency still stays out of
4
85
  `audit`.** The unreadable-manifest exception only applies when the package
5
86
  name is in `dsh.profile.bundles`; a package that is neither declared there nor
package/README.md CHANGED
@@ -133,6 +133,8 @@ next: npm install && npm test && npm run doctor
133
133
 
134
134
  What you get is not a snippet: it is a plugin whose `doctor` already passes (`engines.dsh`, the patch file, the `files` list), with a client bundle that registers a sidebar tab, a testkit test for it, and a CI workflow that runs both. `init` refuses a directory that is not empty unless you pass `--force`, and refuses a name npm would refuse — those are the two mistakes that cost the most time later.
135
135
 
136
+ Every command that takes a path expands a leading `~` before touching the filesystem. The tool, not the shell, expands `~` for these arguments: `cmd` and PowerShell pass `"~/my-panel"` through literally, while a POSIX shell usually expands it first. `init '~/my-panel' --name my-panel` writes into your home directory (the same files `init ~/my-panel` writes on a POSIX shell), and `doctor '~/my-panel'` reads it back. The Windows spelling `~\my-panel` works too; a directory literally named `~` is never created.
137
+
136
138
  ## Where it lives
137
139
 
138
140
  The checker is docked **under the conversation**, above the input bar: a single
@@ -377,8 +379,9 @@ forgets `client.js` passes it and fails only after `npm i`.
377
379
 
378
380
  `command: doctor` stops at the manifest checks (fast, no install), and
379
381
  `command: index` audits `market/index.json` instead, failing on any version whose
380
- `engines.dsh` is missing or is not a semver range. Pin `version:` if you would
381
- rather not track the latest release.
382
+ `engines.dsh` is missing or is not a semver range (a malformed value such as
383
+ `>=banana`, or a single pinned version such as `0.2.0`, both fail). Pin
384
+ `version:` if you would rather not track the latest release.
382
385
 
383
386
  ## Check a plugin you have not cloned
384
387
 
@@ -406,8 +409,12 @@ file. Reading `package.json` over the API is enough to name it.
406
409
 
407
410
  What it can see, and what it cannot:
408
411
 
409
- - Manifest checks (`engines.dsh`, `files`, `dsh.client`, `exports`) run on the
410
- real `package.json`.
412
+ - Manifest checks (`engines.dsh`, `dsh field`, `files`, `dsh.client`,
413
+ `exports`) run on the real `package.json`.
414
+ - README checks (`readme`) run on the text GitHub serves: the README must have
415
+ a `Requirements` heading and must state the host range `package.json`
416
+ declares. A repository whose checkout fails `readme` fails the remote check
417
+ too, with the same sentence.
411
418
  - File checks (does `exports["./client"]` point at a file that exists, does the
412
419
  root export `apply`) need the tree. A package that runs `prepack`,
413
420
  `prepublishOnly`, `prepare` or `build` publishes files it does not commit, so
@@ -438,11 +445,12 @@ verdict, and the remaining entries are reported without another request.
438
445
 
439
446
  ### Will this plugin install on my DSH?
440
447
 
441
- The seven compatibility reports all end with the same question. Add `--host
442
- <version>` to a remote audit and it answers that question for one repository.
443
- This is a real run against `L3n3L/dsh-resume`, a plugin whose declared range
444
- stops before DSH 0.2.0, checked against the `0.2.2-alpha.3` canary from the
445
- reports:
448
+ The eight compatibility reports, from four repositories, all end with the same
449
+ question. Add `--host <version>` to a remote audit and it answers that question
450
+ for one repository. This is the output for `L3n3L/dsh-resume`, a real plugin
451
+ whose declared range stops before DSH 0.2.0, checked against the
452
+ `0.2.2-alpha.3` canary from the reports. The checked-in sample is a frozen 0.1.3
453
+ snapshot, so the line stays true as the upstream repository changes:
446
454
 
447
455
  ```sh
448
456
  $ dsh-plugin audit --remote L3n3L/dsh-resume --host 0.2.2-alpha.3
@@ -453,9 +461,11 @@ summary: 1 repository — 0 clean, 1 failing (1 problem), 0 unreadable, 0 rate-l
453
461
 
454
462
  The verdict comes first: `incompatible` means the range in `package.json` does
455
463
  not accept the host, so the installer rejects the plugin before it unpacks it.
456
- This run exits `1`. The same answer is reproducible without a GitHub request —
457
- the manifest is checked in under `examples/compatibility-sample/`, and this
458
- command feeds it through the real CLI path:
464
+ This run exits `1`. The same answer is reproducible without a GitHub request:
465
+ the checked-in snapshot under `examples/compatibility-sample/` keeps the 0.1.3
466
+ manifest fields that decide compatibility, and its `## Requirements` heading
467
+ isolates the host-range answer. This command feeds that snapshot through the
468
+ real CLI path:
459
469
 
460
470
  ```sh
461
471
  $ node scripts/compatibility-sample.mjs
@@ -463,7 +473,11 @@ $ node scripts/compatibility-sample.mjs
463
473
 
464
474
  (`npm run compatibility` runs the same script.) The test suite runs that
465
475
  command and compares its output with the block above, so the sample cannot
466
- drift from the formatter or from the README.
476
+ drift from the formatter or from the README. Running
477
+ `dsh-plugin audit --remote L3n3L/dsh-resume --host 0.2.2-alpha.3` without the
478
+ sample audits the repository's current default branch instead; a README or
479
+ manifest change since 0.1.3 can add another `readme` or manifest failure to the
480
+ same row.
467
481
 
468
482
  The line carries the range `package.json` declares and one of `compatible`,
469
483
  `incompatible`, or `unknown` against that host version. `unknown` is the honest
@@ -504,7 +518,13 @@ summary: 4 repositories — 1 clean, 1 failing (1 problem), 0 unreadable, 2 rate
504
518
 
505
519
  The parenthesised count is the number of failed checks, not the number of failing
506
520
  repositories: one repository that fails both `engines.dsh` and its client
507
- declaration prints `1 failing (2 problems)`.
521
+ declaration prints `1 failing (2 problems)`. A repository whose `package.json`
522
+ has an empty `dsh` field and no `dsh.bundle.patch` is `failing` here too: the
523
+ batch runs the same `dsh field` check as `doctor`, and the `--json` finding
524
+ carries that failure even though no patch path was declared to check. A README
525
+ with no `Requirements` heading is treated the same way: the batch asks the same
526
+ `readme` question as a checkout, so the row is `failing`, the `--json` finding
527
+ names `readme`, and the run exits `1` instead of reporting the repository clean.
508
528
 
509
529
  The command exits `1` when any repository is failing, unreadable, or
510
530
  rate-limited, and `0` only when every repository in the list is clean. `--from`
@@ -655,8 +675,9 @@ the diff in the terminal.
655
675
 
656
676
  | Check | Why it matters |
657
677
  | --- | --- |
678
+ | `name` | npm publishes and installs by this field; a missing, empty or non-npm name would otherwise pass `doctor` and fail later at publish or `npm pack` |
658
679
  | `version` | The tag is built from it; a malformed version produces a tag nobody can install |
659
- | `engines.dsh` | The market index copies this into every version entry. Missing it, or a value that is not a semver range, fails the index PR |
680
+ | `engines.dsh` | The market index copies this into every version entry. Missing it, or a value that is not a semver range (including a pinned version such as `0.2.0`), fails the index PR |
660
681
  | `readme` | A `Requirements` section that states the declared range, so an install failure is predictable |
661
682
  | `dsh field` | `dsh.bundle.patch` must exist for the host to load the plugin |
662
683
  | `patch file` | The path declared above must be a real file |
@@ -664,7 +685,7 @@ the diff in the terminal.
664
685
  | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` |
665
686
  | `root export` | The loader imports the bare package name; if that module is the CLI (or exports no `apply`), the row mounts nothing while the install reports success |
666
687
 
667
- Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged.
688
+ Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged. `doctor --remote` and `audit --remote` run the same manifest and README checks (`name`, `version`, `engines.dsh`, `dsh field`, `files list`, `readme`) against the `package.json` and README GitHub serves, then check the files the manifest points at, so a bad package name or a README with no Requirements heading is reported before a clone or install. The `name` check is pinned at the process boundary: `npm test` expects the shipped CLI to reject a missing, empty and malformed name (`accepted=0/3`) and to accept a valid plain or scoped control.
668
689
 
669
690
  ## Repair what `doctor` finds
670
691
 
@@ -750,9 +771,9 @@ checkout.
750
771
 
751
772
  Start from the repository name in the hub issue: `PrismLean/dsh-run-guard`, one
752
773
  of the repositories in the 3 November install-failure audit. You do not need a
753
- checkout to learn what is wrong. `doctor --remote` reads `package.json` and the
754
- files it points at through the GitHub API and prints the same verdict it would
755
- give a folder:
774
+ checkout to learn what is wrong. `doctor --remote` reads `package.json`, the
775
+ README and the files the manifest points at through the GitHub API and prints
776
+ the same verdict it would give a folder:
756
777
 
757
778
  ```sh
758
779
  $ npx dsh-plugin-toolkit@latest doctor --remote PrismLean/dsh-run-guard
@@ -783,6 +804,11 @@ dsh-plugin fix: would write engines.dsh ">=0.2.0" (was missing) in PrismLean/dsh
783
804
  remote repositories are read-only; nothing written; apply this diff in your checkout
784
805
  ```
785
806
 
807
+ When `package.json` already declares a range that clears the check, there is
808
+ nothing to apply: the command prints `ok engines.dsh is already "<range>";
809
+ nothing to apply` and exits `0`, the same no-op as `fix --engines` on a
810
+ checkout. No diff and no patch file is written.
811
+
786
812
  To apply it, clone the repository, save that diff with `--patch`, and apply it
787
813
  in the checkout:
788
814
 
@@ -796,21 +822,24 @@ $ git apply /tmp/dsh-run-guard-engines.patch
796
822
 
797
823
  `--patch` creates parent directories and refuses to replace an existing file
798
824
  unless you pass `--force`; its output names the file, and the repository it read
799
- is still untouched. The same host-aware plan works with `--patch`, and
800
- `audit --remote --host <version> --patch-dir <dir>` writes host-targeted repairs
801
- for a whole list. `git apply --check` is the dry run: it fails before changing
802
- anything if the manifest moved since the diff was printed. Commit the applied
803
- change as you would any other edit.
804
-
805
- Then run `npx dsh-plugin-toolkit@latest doctor .` in the checkout. A checkout
806
- also reads the README text, so it can name a follow-up the remote read could
807
- not see — for `PrismLean/dsh-run-guard`, the README still has no Requirements
808
- section. [Repair a failed
825
+ is still untouched. The same host-aware plan works with `--patch`:
826
+ `fix <owner>/<repo> --remote --engines --host 0.3.0 --patch repair.patch` plans
827
+ `>=0.3.0 <1.0.0` and prints why. After cloning, `fix . --engines --host 0.3.0
828
+ --write` applies that same range; either path writes one that accepts the host
829
+ and rejects the next major. `audit --remote --host <version> --patch-dir <dir>`
830
+ writes host-targeted repairs for a whole list. `git apply --check` is the dry
831
+ run: it fails before changing anything if the manifest moved since the diff was
832
+ printed. Commit the applied change as you would any other edit.
833
+
834
+ Then run `npx dsh-plugin-toolkit@latest doctor .` in the checkout. Both the
835
+ remote and checkout commands now read the README text, so a `readme` line names
836
+ the same follow-up in either place — for `PrismLean/dsh-run-guard`, the README
837
+ still has no Requirements section. [Repair a failed
809
838
  install](https://github.com/WJDdidi-1/dsh-plugin-toolkit/blob/main/docs/repair.md#readme)
810
- has the smallest edit for each remaining line. Once the branch is pushed,
811
- `doctor --remote PrismLean/dsh-run-guard` no longer reports `engines.dsh`. If
812
- the diff does not apply because the file changed, run the remote fixer again —
813
- it always starts from the current `package.json`.
839
+ has the smallest edit for each remaining line. Once the branch with that README
840
+ edit is pushed, `doctor --remote PrismLean/dsh-run-guard` no longer reports
841
+ `engines.dsh` or `readme`. If the diff does not apply because the file changed,
842
+ run the remote fixer again — it always starts from the current `package.json`.
814
843
 
815
844
  ## When an install fails
816
845
 
@@ -861,10 +890,13 @@ $ npx dsh-plugin-toolkit explain "plugin install failed" ./my-panel
861
890
  The same checkout argument works after the log:
862
891
  `dsh-plugin explain --log ~/.dsh/logs/install.log ./my-panel`.
863
892
 
864
- On Windows, `cmd` and PowerShell leave the tilde alone:
865
- `--log ~\.dsh\logs\install.log` expands exactly like
866
- `--log ~/.dsh/logs/install.log`. A log that cannot be read exits `2` and names
867
- the resolved absolute path it tried, never a directory literally named `~`.
893
+ On Windows, `cmd` and PowerShell leave the tilde alone. Every user-named path
894
+ expands it: the directory argument of `init`, `doctor`, `fix`, `verify`, `dev`
895
+ and `release`, and the `--home`, `--market`, `--dest`, `--from`, `--patch-dir`,
896
+ `--patch`, `--log` and `--index` flags. `--log ~\.dsh\logs\install.log`
897
+ expands exactly like `--log ~/.dsh/logs/install.log`. A log that cannot be read
898
+ exits `2` and names the resolved absolute path it tried, never a directory
899
+ literally named `~`.
868
900
 
869
901
  Text it does not recognise exits `2` instead of guessing: a wrong diagnosis
870
902
  sends you editing the wrong file. A log with no known cause also exits `2` and
@@ -985,9 +1017,13 @@ merged
985
1017
 
986
1018
  | Code | Meaning |
987
1019
  | --- | --- |
988
- | 0 | Done, or nothing to complain about |
1020
+ | 0 | Done, or nothing to complain about — including `fix --remote` when `engines.dsh` is already a valid range |
989
1021
  | 1 | A check failed, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
990
- | 2 | Unknown command |
1022
+ | 2 | Unknown command, invalid usage, or a remote request that could not be completed |
1023
+
1024
+ `fix <owner>/<repo> --remote` exits `0` both when it prints a diff for a missing
1025
+ `engines.dsh` and when the manifest already declares a range that clears the
1026
+ check; the second case prints `ok ... nothing to apply` and writes no diff.
991
1027
 
992
1028
  ## What is not here yet
993
1029
 
@@ -998,6 +1034,56 @@ Honest list, so nobody plans around a feature that does not exist:
998
1034
  - **`dev --host` is not covered by CI.** The unit tests use a synthetic event stream; the live path is exercised by hand against a running app, on macOS only.
999
1035
  - **No Windows testing of the `dev` file watcher.** The Windows CI job runs the whole suite, but the watcher is only asserted against a temp directory, not a real profile.
1000
1036
 
1037
+ ## FAQ
1038
+
1039
+ **Do I need the app running to check a plugin?**
1040
+ No. `doctor` reads a folder and writes nothing, `mount` renders a client bundle
1041
+ in Node, and `verify` packs the plugin and installs that tarball into a
1042
+ temporary directory. None of them needs the running app.
1043
+
1044
+ ```sh
1045
+ npx dsh-plugin-toolkit@latest verify .
1046
+ ```
1047
+
1048
+ **Will `doctor --fix` rewrite my `package.json`?**
1049
+ Only with `--write`. Without it the command prints the plan and stops; with it,
1050
+ it applies the edits in the plan and runs the checks again.
1051
+
1052
+ **`doctor` passes, but the panel still does not appear. What next?**
1053
+ `doctor` checks the manifest and source without executing the plugin. `verify`
1054
+ packs the plugin, installs the tarball and mounts the bundle, so it catches a
1055
+ root module or client bundle that throws when the loader loads it. If `verify`
1056
+ passes too, work through [When the panel does not
1057
+ appear](#when-the-panel-does-not-appear).
1058
+
1059
+ **Can I check a plugin before cloning it?**
1060
+ Yes. `doctor --remote owner/repo` reads the repository's `package.json`, README
1061
+ and the files it declares over the GitHub API, and writes nothing:
1062
+
1063
+ ```sh
1064
+ npx dsh-plugin-toolkit@latest doctor --remote V1ki/dsh-plugin-subscriptions
1065
+ ```
1066
+
1067
+ **Will a plugin install on the DSH version I run?**
1068
+ Add `--host <version>` to a remote audit. It prints `compatible`,
1069
+ `incompatible` or `unknown` against that host, and an `incompatible` result is
1070
+ counted as failing and exits `1`:
1071
+
1072
+ ```sh
1073
+ npx dsh-plugin-toolkit@latest audit --remote L3n3L/dsh-resume --host 0.2.2-alpha.3
1074
+ ```
1075
+
1076
+ **What should CI run?**
1077
+ The composite action's default `command` is `verify`, the only check that reads
1078
+ the tarball. Use `command: doctor` for a fast manifest-only gate, or
1079
+ `command: index` to audit the market index:
1080
+
1081
+ ```yaml
1082
+ - uses: WJDdidi-1/dsh-plugin-toolkit@v1
1083
+ with:
1084
+ dir: plugin
1085
+ ```
1086
+
1001
1087
  ## Changelog
1002
1088
 
1003
1089
  [`CHANGELOG.md`](CHANGELOG.md) lists what changed in each release, including
@@ -1,10 +1,19 @@
1
1
  # dsh-resume
2
2
 
3
- The manifest in this folder is the one the compatibility sample audits. Its
4
- `engines.dsh` range is the real one from `L3n3L/dsh-resume@0.1.3`:
3
+ This folder is a frozen snapshot of the files the compatibility sample audits.
4
+ Its `engines.dsh` range is the real one from `L3n3L/dsh-resume@0.1.3`:
5
+
6
+ ## Requirements
7
+
8
+ - DeepSeek Harness `>=0.1.0-rc.6 <0.2.0-0`
5
9
 
6
10
  ```json
7
11
  "engines": {
8
12
  "dsh": ">=0.1.0-rc.6 <0.2.0-0"
9
13
  }
10
14
  ```
15
+
16
+ The heading is here on purpose: the sample isolates the host-range verdict, and
17
+ the remote audit still checks README requirements. Upstream's localized README
18
+ does not use a `## Requirements` heading, so a live audit of the repository can
19
+ also add a `readme` failure to the same row.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-resume",
3
3
  "version": "0.1.3",
4
- "description": "A checked-in copy of the manifest the README audits: a real plugin whose engines.dsh range stops before DSH 0.2.0.",
4
+ "description": "A frozen 0.1.3 snapshot of the manifest the README audits, keeping the fields that decide compatibility: a real plugin whose engines.dsh range stops before DSH 0.2.0.",
5
5
  "type": "module",
6
6
  "main": "index.js",
7
7
  "exports": {
package/lib/audit.mjs CHANGED
@@ -14,7 +14,8 @@ import path from 'node:path';
14
14
  import { checkHostCompatibility, doctor, hostRange, version as manifestVersion } from './doctor.mjs';
15
15
  import { hostCompatibility } from './compat.mjs';
16
16
  import { readGraph } from './dev.mjs';
17
- import { auditRemote, expandHome, fixRemote } from './remote.mjs';
17
+ import { auditRemote, fixRemote } from './remote.mjs';
18
+ import { resolvePath } from './paths.mjs';
18
19
 
19
20
  export { hostCompatibility } from './compat.mjs';
20
21
 
@@ -55,7 +56,8 @@ export function parseJobs(value) {
55
56
  * same thing.
56
57
  */
57
58
  export function readProfileBundles({ home = DEFAULT_HOME, profile } = {}) {
58
- const file = path.join(home, 'profiles', profile, 'package.json');
59
+ const root = resolvePath(home);
60
+ const file = path.join(root, 'profiles', profile, 'package.json');
59
61
  if (fs.existsSync(file) === false) return { file, bundles: [] };
60
62
  try {
61
63
  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -111,7 +113,8 @@ function unreadableInstalled({ dir, name, profile, manifestPath, message }) {
111
113
 
112
114
  /** Every package folder inside every profile, scoped names included. */
113
115
  export function listInstalled({ home = DEFAULT_HOME } = {}) {
114
- const profiles = path.join(home, 'profiles');
116
+ const root = resolvePath(home);
117
+ const profiles = path.join(root, 'profiles');
115
118
  if (fs.existsSync(profiles) === false) return [];
116
119
  const found = [];
117
120
  for (const profile of fs.readdirSync(profiles).sort()) {
@@ -320,7 +323,7 @@ export async function readRemoteTargets({ from, stdin = process.stdin, readFile
320
323
  const text = await readStdin(stdin);
321
324
  return parseRemoteList(text, 'standard input');
322
325
  }
323
- const file = path.resolve(expandHome(source));
326
+ const file = resolvePath(source);
324
327
  let text;
325
328
  try {
326
329
  text = readFile(file, 'utf8');
@@ -480,7 +483,7 @@ export async function auditRemoteTargets(
480
483
  // an empty directory is the honest answer to "no repairs needed".
481
484
  let patchRoot = null;
482
485
  if (patchDir !== undefined && patchDir !== null && String(patchDir).trim() !== '') {
483
- patchRoot = path.resolve(expandHome(patchDir));
486
+ patchRoot = resolvePath(patchDir);
484
487
  fs.mkdirSync(patchRoot, { recursive: true });
485
488
  }
486
489
 
package/lib/benchmark.mjs CHANGED
@@ -43,7 +43,7 @@ const MANIFEST = {
43
43
 
44
44
  const FILES = {
45
45
  'package.json': JSON.stringify(MANIFEST),
46
- 'README.md': '# benchmark-plugin\n\nRequires dsh >=0.2.0.\n',
46
+ 'README.md': '# benchmark-plugin\n\n## Requirements\n\nRequires dsh >=0.2.0.\n',
47
47
  };
48
48
 
49
49
  /** Read the named list, first `limit` entries, using the same parser `--from` uses. */
package/lib/cli.mjs CHANGED
@@ -8,7 +8,8 @@ import path from 'node:path';
8
8
 
9
9
  import { doctor } from './doctor.mjs';
10
10
  import { DEFAULT_ENGINES, doctorFix, fixEngines } from './fix.mjs';
11
- import { auditRemote, expandHome, fixRemote } from './remote.mjs';
11
+ import { auditRemote, fixRemote } from './remote.mjs';
12
+ import { expandHome, resolvePath } from './paths.mjs';
12
13
  import { init } from './init.mjs';
13
14
  import { verify } from './verify.mjs';
14
15
  import { plan, release } from './release.mjs';
@@ -212,7 +213,7 @@ function printFailures(failures, io = console) {
212
213
  export async function run(argv, io = console, deps = {}) {
213
214
  const [command, ...rest] = argv;
214
215
  const options = flags(rest);
215
- const dir = path.resolve(options.positional[0] ?? '.');
216
+ const dir = resolvePath(options.positional[0] ?? '.');
216
217
 
217
218
  // `--budget` is validated while parsing, so an invalid value stops here:
218
219
  // before the release sequence reads the manifest, tags, or pushes anything.
@@ -358,9 +359,12 @@ export async function run(argv, io = console, deps = {}) {
358
359
  return 2;
359
360
  }
360
361
  if (result.changed !== true) {
362
+ // A manifest that already declares a range clearing the check is a
363
+ // successful repair plan, exactly like the local `fix --engines` no-op:
364
+ // there is no failure to report, so the documented exit code is 0.
361
365
  io.log(`ok engines.dsh is already "${result.range}"; nothing to apply`);
362
366
  if (typeof result.why === 'string' && result.why.length > 0) io.log(` ${result.why}`);
363
- return 1;
367
+ return 0;
364
368
  }
365
369
  const was = result.before === null ? 'missing' : `"${result.before}"`;
366
370
  io.log(`dsh-plugin fix: would write engines.dsh "${result.range}" (was ${was}) in ${result.target.slug}`);
@@ -422,7 +426,7 @@ export async function run(argv, io = console, deps = {}) {
422
426
  let result;
423
427
 
424
428
  if (options.log !== undefined) {
425
- const logFile = path.resolve(expandHome(options.log));
429
+ const logFile = resolvePath(options.log);
426
430
  let log;
427
431
  try {
428
432
  log = fs.readFileSync(logFile, 'utf8');
@@ -464,7 +468,7 @@ export async function run(argv, io = console, deps = {}) {
464
468
  io.log(` fix: ${cause.fix}`);
465
469
  }
466
470
  if (checkout !== undefined) {
467
- const report = doctor(path.resolve(checkout));
471
+ const report = doctor(resolvePath(checkout));
468
472
  const { hits } = verdict(result, report.failures);
469
473
  if (hits.length === 0) {
470
474
  io.log(` in ${checkout}: none of those checks fail, so the cause is somewhere else`);
@@ -511,7 +515,12 @@ export async function run(argv, io = console, deps = {}) {
511
515
  }
512
516
 
513
517
  if (command === 'index') {
514
- const target = options.index ?? (dir.endsWith('.json') === true ? dir : path.join(dir, 'market/index.json'));
518
+ const target =
519
+ options.index === undefined
520
+ ? dir.endsWith('.json') === true
521
+ ? dir
522
+ : path.join(dir, 'market/index.json')
523
+ : resolvePath(options.index);
515
524
  const index = readIndex(target);
516
525
  let problems = 0;
517
526
  for (const plugin of index.plugins ?? []) {
@@ -581,14 +590,19 @@ export async function run(argv, io = console, deps = {}) {
581
590
  }
582
591
  return result.ok === true ? 0 : 1;
583
592
  }
584
- const result = await audit({ home: options.home, host: options.host, timeoutMs: options.timeout, io });
593
+ const result = await audit({
594
+ home: options.home === undefined ? undefined : resolvePath(options.home),
595
+ host: options.host,
596
+ timeoutMs: options.timeout,
597
+ io,
598
+ });
585
599
  return result.ok === true ? 0 : 1;
586
600
  }
587
601
 
588
602
  if (command === 'dev') {
589
603
  const { dev } = await import('./dev.mjs');
590
604
  return dev({
591
- dir: path.resolve(options.positional[0] ?? '.'),
605
+ dir: resolvePath(options.positional[0] ?? '.'),
592
606
  dest: options.dest,
593
607
  entry: options.entry,
594
608
  build: options.build,
@@ -608,7 +622,7 @@ export async function run(argv, io = console, deps = {}) {
608
622
  }
609
623
  const { mountClient } = await import('./testkit/index.mjs');
610
624
  const panel = await mountClient({
611
- file: path.resolve(file),
625
+ file: resolvePath(file),
612
626
  slot: options.slot ?? 'sidebar.right.pane.tab',
613
627
  surface: options.surface ?? 'sidebar',
614
628
  });
@@ -625,7 +639,13 @@ export async function run(argv, io = console, deps = {}) {
625
639
 
626
640
  if (options.dryRun === true) {
627
641
  io.log(`dry run: ${name}@${version}`);
628
- const planned = plan({ dir, version, name, tagPrefix: options.tagPrefix, indexFile: options.index });
642
+ const planned = plan({
643
+ dir,
644
+ version,
645
+ name,
646
+ tagPrefix: options.tagPrefix,
647
+ indexFile: options.index === undefined ? undefined : expandHome(options.index),
648
+ });
629
649
  for (const step of planned.steps) {
630
650
  io.log(` ${step.runs === false ? '·' : '→'} ${step.title}`);
631
651
  io.log(` ${step.command}`);
@@ -640,8 +660,8 @@ export async function run(argv, io = console, deps = {}) {
640
660
 
641
661
  const result = await release({
642
662
  dir,
643
- indexFile: options.index,
644
- marketDir: options.market,
663
+ indexFile: options.index === undefined ? undefined : expandHome(options.index),
664
+ marketDir: options.market === undefined ? undefined : resolvePath(options.market),
645
665
  publish: options.publish === true,
646
666
  tagPrefix: options.tagPrefix,
647
667
  budgetMs: options.budget === undefined ? undefined : options.budget * 1000,
package/lib/compat.mjs CHANGED
@@ -123,24 +123,29 @@ function comparator(op, version) {
123
123
  function lowerBounds(partial, inclusive) {
124
124
  const version = filled(partial);
125
125
  if (inclusive === true) return [comparator('>=', version)];
126
- if (partial.patch === null) {
127
- return [comparator('>=', full(version.major, version.minor + 1, 0))];
128
- }
126
+ // The missing component decides the next boundary: `>1` starts at 2.0.0,
127
+ // while `>1.2` starts at 1.3.0. Check the major-only case first, or the
128
+ // filled-in minor would turn `>1` into `>=1.1.0` and accept 1.2.3 — a
129
+ // version npm rejects.
129
130
  if (partial.minor === null) {
130
131
  return [comparator('>=', full(version.major + 1, 0, 0))];
131
132
  }
133
+ if (partial.patch === null) {
134
+ return [comparator('>=', full(version.major, version.minor + 1, 0))];
135
+ }
132
136
  return [comparator('>', version)];
133
137
  }
134
138
 
135
139
  function upperBounds(partial, inclusive) {
136
140
  const version = filled(partial);
137
141
  if (inclusive === true) {
138
- if (partial.patch === null) return [comparator('<', full(version.major, version.minor + 1, 0))];
142
+ // `<=1` includes all of 1.x, so its exclusive ceiling is 2.0.0, not 1.1.0.
139
143
  if (partial.minor === null) return [comparator('<', full(version.major + 1, 0, 0))];
144
+ if (partial.patch === null) return [comparator('<', full(version.major, version.minor + 1, 0))];
140
145
  return [comparator('<=', version)];
141
146
  }
142
- if (partial.patch === null) return [comparator('<', full(version.major, version.minor, 0))];
143
147
  if (partial.minor === null) return [comparator('<', full(version.major, 0, 0))];
148
+ if (partial.patch === null) return [comparator('<', full(version.major, version.minor, 0))];
144
149
  return [comparator('<', version)];
145
150
  }
146
151
 
@@ -175,7 +180,9 @@ function plainBounds(partial) {
175
180
  }
176
181
 
177
182
  function expandToken(token) {
178
- const match = /^(\^|~|>=|<=|>|<|=)?(.*)$/u.exec(token);
183
+ // `~>` is npm's older spelling of `~`; package.json files in the wild still
184
+ // use it, and npm accepts both, so the answer here has to as well.
185
+ const match = /^(~>|\^|~|>=|<=|>|<|=)?(.*)$/u.exec(token);
179
186
  if (match === null) return null;
180
187
  const operator = match[1] ?? '=';
181
188
  const body = match[2].trim();
@@ -186,7 +193,7 @@ function expandToken(token) {
186
193
  if (partial.major === null) return null;
187
194
  return caretBounds(partial);
188
195
  }
189
- if (operator === '~') {
196
+ if (operator === '~' || operator === '~>') {
190
197
  if (partial.major === null) return null;
191
198
  return tildeBounds(partial);
192
199
  }