dsh-plugin-toolkit 0.20.12 → 0.20.14
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 +101 -0
- package/README.md +116 -37
- package/examples/compatibility-sample/README.md +11 -2
- package/examples/compatibility-sample/package.json +1 -1
- package/lib/audit.mjs +8 -5
- package/lib/benchmark.mjs +42 -6
- package/lib/cli.mjs +28 -11
- package/lib/compat.mjs +14 -7
- package/lib/dev.mjs +15 -11
- package/lib/doctor.mjs +213 -16
- package/lib/fix.mjs +66 -28
- package/lib/github.mjs +4 -3
- package/lib/index-file.mjs +3 -2
- package/lib/init.mjs +8 -3
- package/lib/paths.mjs +38 -0
- package/lib/release.mjs +27 -15
- package/lib/remote.mjs +39 -49
- package/lib/verify.mjs +7 -5
- package/package.json +1 -1
- package/scripts/benchmark-audit.mjs +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,104 @@
|
|
|
1
|
+
## 0.20.14
|
|
2
|
+
|
|
3
|
+
- **The `--jobs` benchmark asserts work, not wall-clock speed.** The throughput
|
|
4
|
+
test used to fail whenever the batched run was not at least 25% faster, which
|
|
5
|
+
is noise when the whole measurement is tens of milliseconds on a loaded
|
|
6
|
+
runner. It now checks what batching actually guarantees: the same named
|
|
7
|
+
results and the same number of API requests at `--jobs 1` and the default
|
|
8
|
+
width, no overlap at `--jobs 1`, and real overlap (never above the requested
|
|
9
|
+
width) after batching. The benchmark still prints before/after wall clock and
|
|
10
|
+
the speedup as context, but no assertion depends on them, so a slow machine
|
|
11
|
+
can no longer block the publish gate.
|
|
12
|
+
- **`npm run benchmark -- --latency` reaches the measured run.** The script
|
|
13
|
+
parsed the flag into `latency` while `runBenchmark` reads `latencyMs`, so the
|
|
14
|
+
option was accepted and ignored and every run used the default 500 ms. Both
|
|
15
|
+
names now agree, and a regression test runs the shipped script with
|
|
16
|
+
`--limit 1 --latency 1` and checks the printed delay.
|
|
17
|
+
- **`doctor` reads the root export from code, not from prose.** A root module
|
|
18
|
+
whose only `apply` was inside a comment, string, template or regex literal
|
|
19
|
+
used to pass the `root export` check, while `verify --no-mount` rejected the
|
|
20
|
+
installed package. The check now removes those non-code spans, without
|
|
21
|
+
importing or running the plugin, and accepts only a real exported `apply`:
|
|
22
|
+
`export function apply`, `export const apply = ...`, `export { apply }` and
|
|
23
|
+
the CommonJS `module.exports` forms still pass, while
|
|
24
|
+
`// TODO: export function apply() {}` is a failure. The same helper backs
|
|
25
|
+
`doctor --remote`, so the checkout and the published repository agree.
|
|
26
|
+
- **`doctor` and `verify --no-mount` are pinned to one root-export verdict at
|
|
27
|
+
the process boundary.** A regression test spawns the shipped CLI on the
|
|
28
|
+
comment-only fixture and requires both commands to exit `1`, so the source
|
|
29
|
+
parser and the installed import cannot disagree again. The README and
|
|
30
|
+
`docs/repair.md` now state the exact rule: the resolved root is read as
|
|
31
|
+
source, comments and string/template/regex contents are removed, and only a
|
|
32
|
+
real `export function apply`, `export const apply = ...` (also `let` and
|
|
33
|
+
`var`), `export { apply }` (including aliases), `exports.apply = ...` or
|
|
34
|
+
`module.exports = { apply }` passes.
|
|
35
|
+
|
|
36
|
+
## 0.20.13
|
|
37
|
+
|
|
38
|
+
- **The compatibility sample says which snapshot it answers for.** The README
|
|
39
|
+
now names the eight reports behind "will this plugin install on my DSH?" and
|
|
40
|
+
states that the quoted `incompatible` line comes from the frozen 0.1.3 sample
|
|
41
|
+
under `examples/compatibility-sample/`, not from whatever the upstream
|
|
42
|
+
repository's default branch contains today. The sample README explains why it
|
|
43
|
+
keeps a `## Requirements` heading even though the upstream README is
|
|
44
|
+
localized: it isolates the host-range verdict, while a live audit also runs
|
|
45
|
+
the README check and can add a `readme` failure to the same row.
|
|
46
|
+
- **A leading `~` expands in every user-named path, not just `--log`.** On
|
|
47
|
+
`cmd` and PowerShell the shell leaves the tilde literal, so
|
|
48
|
+
`init '~/my-panel' --name my-panel` used to create a directory literally
|
|
49
|
+
named `~` in the current folder, and `doctor '~/my-panel'` then looked in
|
|
50
|
+
the same wrong place. Both the CLI and the exported `init`/`doctor`/`fix`/
|
|
51
|
+
`verify`/`dev`/`release` functions now expand `~/` and `~\` before any
|
|
52
|
+
filesystem access, as do `--home`, `--market`, `--dest`, `--from`,
|
|
53
|
+
`--patch-dir`, `--patch`, `--log` and `--index`. The scaffold lands in
|
|
54
|
+
`$HOME/my-panel`, `doctor` exits `0` on it, and no literal `~` folder is
|
|
55
|
+
created.
|
|
56
|
+
- **Major-only comparator ranges get npm's boundaries.** `audit --remote
|
|
57
|
+
<owner/repo> --host <version>` filled a missing minor with 0 before deciding
|
|
58
|
+
the edge of `<=1`, `>1` and hyphen ranges such as `1.2.3 - 2`, so it called
|
|
59
|
+
1.2.3 compatible with `<=1` and incompatible with `>1` — the reverse of what
|
|
60
|
+
the installer does. The same answer is used by `doctor --remote`, `--json`
|
|
61
|
+
and `--patch-dir`. The older `~>` spelling of `~` is now parsed too, instead
|
|
62
|
+
of being reported as unknown. Regression tests pin all four forms against npm
|
|
63
|
+
semver.
|
|
64
|
+
- **`doctor --remote` reads the README the way a checkout does.** A published
|
|
65
|
+
repository whose README has no `## Requirements` heading, or whose
|
|
66
|
+
Requirements section omits the `engines.dsh` range it declares, used to print
|
|
67
|
+
`ok` and exit `0`, while the same checkout failed the `readme` check. The
|
|
68
|
+
remote audit now reports that failure and exits `1`; `audit --remote` shares
|
|
69
|
+
the check, so both the single-repository and `--from` batch forms print the
|
|
70
|
+
`failing` row and carry its `readme` failure in the `--json` finding. A README
|
|
71
|
+
that states the declared range still exits `0`.
|
|
72
|
+
- **`dsh-plugin doctor` checks the package name before it packs anything.** A
|
|
73
|
+
`package.json` whose `name` is missing, empty, or not a valid npm package name
|
|
74
|
+
(for example `My Plugin!`) used to print `ok` and exit `0`, while
|
|
75
|
+
`verify --no-mount` failed later at `npm pack`. The manifest preflight now
|
|
76
|
+
reports a `name:` failure and exits `1`, and the same check reaches
|
|
77
|
+
`doctor --remote` and `audit --remote` through the shared manifest check.
|
|
78
|
+
`init` uses the same validator, so a scaffold's name and the check that blesses
|
|
79
|
+
it stay in step. `npm test` pins the result through the shipped CLI: missing,
|
|
80
|
+
empty and malformed names all exit `1` (`accepted=0/3`), while a valid plain or
|
|
81
|
+
scoped name exits `0`.
|
|
82
|
+
- **`doctor --remote` runs the same `dsh` field check as local `doctor`.** A
|
|
83
|
+
repository whose `package.json` has `dsh: {}` and no `dsh.bundle.patch` used
|
|
84
|
+
to print `ok` and exit `0`, because the remote file checks only looked for a
|
|
85
|
+
patch that was declared. It now reports `dsh field: dsh.bundle is missing` and
|
|
86
|
+
exits `1`; the failure is also carried into `audit --remote`, and a clean
|
|
87
|
+
repository still exits `0`.
|
|
88
|
+
- **`fix --remote` can aim the range at the host that rejected the install.**
|
|
89
|
+
`fix <owner>/<repo> --remote --engines --host 0.3.0 --patch repair.patch`
|
|
90
|
+
plans the same `>=0.3.0 <1.0.0` range that `fix . --engines --host 0.3.0
|
|
91
|
+
--write` writes in a checkout. The remote planner and the local writer share
|
|
92
|
+
one decision, so the patch both accepts the host and rejects the next major,
|
|
93
|
+
prints why, and a non-semver `--host` exits `2` before creating a patch file.
|
|
94
|
+
- **`release` refuses a bad host range instead of throwing at the index step.**
|
|
95
|
+
A malformed `engines.dsh` that reached the market-entry builder used to escape
|
|
96
|
+
as an exception, outside the normal `{ ok: false, stage, failures }` result.
|
|
97
|
+
`release` now reports that problem in the `index` stage and writes nothing; a
|
|
98
|
+
manifest with the same bad range is already stopped by the preflight, so the
|
|
99
|
+
command returns before a tag is created. The regression test checks that the
|
|
100
|
+
index file is byte-for-byte unchanged and that the registry is never called.
|
|
101
|
+
|
|
1
102
|
## 0.20.12
|
|
2
103
|
|
|
3
104
|
- **`dsh-plugin fix <owner>/<repo> --remote` treats an already-correct range as
|
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
|
|
381
|
-
|
|
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`,
|
|
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
|
|
442
|
-
<version>` to a remote audit and it answers that question
|
|
443
|
-
This is
|
|
444
|
-
stops before DSH 0.2.0, checked against 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
|
|
458
|
-
|
|
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,9 @@ 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
|
-
|
|
688
|
+
The `root export` check is a source check, not an install. `doctor` resolves the module the loader imports — `exports["."]` when it is a string or a conditions object (`default`, `import`, `require`, `node`, `module-sync`), otherwise `main` — then removes comments and the contents of string, template and regex literals before looking for a real export. It accepts `export function apply`, `export async function apply`, `export const apply = ...` (also `let` and `var`), `export { apply }` (including `export { helper as apply }`), `exports.apply = ...`, and an `apply` property in `module.exports = { ... }`. A comment such as `// TODO: export function apply() {}` is not an export, and `doctor` never imports or runs the plugin to decide. `verify --no-mount` installs the tarball and imports that same module, so it reaches the same verdict; `npm test` spawns the shipped CLI on the comment-only fixture and requires both commands to exit `1`.
|
|
689
|
+
|
|
690
|
+
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
691
|
|
|
669
692
|
## Repair what `doctor` finds
|
|
670
693
|
|
|
@@ -750,9 +773,9 @@ checkout.
|
|
|
750
773
|
|
|
751
774
|
Start from the repository name in the hub issue: `PrismLean/dsh-run-guard`, one
|
|
752
775
|
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
|
|
754
|
-
files
|
|
755
|
-
give a folder:
|
|
776
|
+
checkout to learn what is wrong. `doctor --remote` reads `package.json`, the
|
|
777
|
+
README and the files the manifest points at through the GitHub API and prints
|
|
778
|
+
the same verdict it would give a folder:
|
|
756
779
|
|
|
757
780
|
```sh
|
|
758
781
|
$ npx dsh-plugin-toolkit@latest doctor --remote PrismLean/dsh-run-guard
|
|
@@ -801,21 +824,24 @@ $ git apply /tmp/dsh-run-guard-engines.patch
|
|
|
801
824
|
|
|
802
825
|
`--patch` creates parent directories and refuses to replace an existing file
|
|
803
826
|
unless you pass `--force`; its output names the file, and the repository it read
|
|
804
|
-
is still untouched. The same host-aware plan works with `--patch
|
|
805
|
-
`
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
827
|
+
is still untouched. The same host-aware plan works with `--patch`:
|
|
828
|
+
`fix <owner>/<repo> --remote --engines --host 0.3.0 --patch repair.patch` plans
|
|
829
|
+
`>=0.3.0 <1.0.0` and prints why. After cloning, `fix . --engines --host 0.3.0
|
|
830
|
+
--write` applies that same range; either path writes one that accepts the host
|
|
831
|
+
and rejects the next major. `audit --remote --host <version> --patch-dir <dir>`
|
|
832
|
+
writes host-targeted repairs for a whole list. `git apply --check` is the dry
|
|
833
|
+
run: it fails before changing anything if the manifest moved since the diff was
|
|
834
|
+
printed. Commit the applied change as you would any other edit.
|
|
835
|
+
|
|
836
|
+
Then run `npx dsh-plugin-toolkit@latest doctor .` in the checkout. Both the
|
|
837
|
+
remote and checkout commands now read the README text, so a `readme` line names
|
|
838
|
+
the same follow-up in either place — for `PrismLean/dsh-run-guard`, the README
|
|
839
|
+
still has no Requirements section. [Repair a failed
|
|
814
840
|
install](https://github.com/WJDdidi-1/dsh-plugin-toolkit/blob/main/docs/repair.md#readme)
|
|
815
|
-
has the smallest edit for each remaining line. Once the branch
|
|
816
|
-
`doctor --remote PrismLean/dsh-run-guard` no longer reports
|
|
817
|
-
the diff does not apply because the file changed,
|
|
818
|
-
it always starts from the current `package.json`.
|
|
841
|
+
has the smallest edit for each remaining line. Once the branch with that README
|
|
842
|
+
edit is pushed, `doctor --remote PrismLean/dsh-run-guard` no longer reports
|
|
843
|
+
`engines.dsh` or `readme`. If the diff does not apply because the file changed,
|
|
844
|
+
run the remote fixer again — it always starts from the current `package.json`.
|
|
819
845
|
|
|
820
846
|
## When an install fails
|
|
821
847
|
|
|
@@ -866,10 +892,13 @@ $ npx dsh-plugin-toolkit explain "plugin install failed" ./my-panel
|
|
|
866
892
|
The same checkout argument works after the log:
|
|
867
893
|
`dsh-plugin explain --log ~/.dsh/logs/install.log ./my-panel`.
|
|
868
894
|
|
|
869
|
-
On Windows, `cmd` and PowerShell leave the tilde alone
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
895
|
+
On Windows, `cmd` and PowerShell leave the tilde alone. Every user-named path
|
|
896
|
+
expands it: the directory argument of `init`, `doctor`, `fix`, `verify`, `dev`
|
|
897
|
+
and `release`, and the `--home`, `--market`, `--dest`, `--from`, `--patch-dir`,
|
|
898
|
+
`--patch`, `--log` and `--index` flags. `--log ~\.dsh\logs\install.log`
|
|
899
|
+
expands exactly like `--log ~/.dsh/logs/install.log`. A log that cannot be read
|
|
900
|
+
exits `2` and names the resolved absolute path it tried, never a directory
|
|
901
|
+
literally named `~`.
|
|
873
902
|
|
|
874
903
|
Text it does not recognise exits `2` instead of guessing: a wrong diagnosis
|
|
875
904
|
sends you editing the wrong file. A log with no known cause also exits `2` and
|
|
@@ -1007,6 +1036,56 @@ Honest list, so nobody plans around a feature that does not exist:
|
|
|
1007
1036
|
- **`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.
|
|
1008
1037
|
- **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.
|
|
1009
1038
|
|
|
1039
|
+
## FAQ
|
|
1040
|
+
|
|
1041
|
+
**Do I need the app running to check a plugin?**
|
|
1042
|
+
No. `doctor` reads a folder and writes nothing, `mount` renders a client bundle
|
|
1043
|
+
in Node, and `verify` packs the plugin and installs that tarball into a
|
|
1044
|
+
temporary directory. None of them needs the running app.
|
|
1045
|
+
|
|
1046
|
+
```sh
|
|
1047
|
+
npx dsh-plugin-toolkit@latest verify .
|
|
1048
|
+
```
|
|
1049
|
+
|
|
1050
|
+
**Will `doctor --fix` rewrite my `package.json`?**
|
|
1051
|
+
Only with `--write`. Without it the command prints the plan and stops; with it,
|
|
1052
|
+
it applies the edits in the plan and runs the checks again.
|
|
1053
|
+
|
|
1054
|
+
**`doctor` passes, but the panel still does not appear. What next?**
|
|
1055
|
+
`doctor` checks the manifest and source without executing the plugin. `verify`
|
|
1056
|
+
packs the plugin, installs the tarball and mounts the bundle, so it catches a
|
|
1057
|
+
root module or client bundle that throws when the loader loads it. If `verify`
|
|
1058
|
+
passes too, work through [When the panel does not
|
|
1059
|
+
appear](#when-the-panel-does-not-appear).
|
|
1060
|
+
|
|
1061
|
+
**Can I check a plugin before cloning it?**
|
|
1062
|
+
Yes. `doctor --remote owner/repo` reads the repository's `package.json`, README
|
|
1063
|
+
and the files it declares over the GitHub API, and writes nothing:
|
|
1064
|
+
|
|
1065
|
+
```sh
|
|
1066
|
+
npx dsh-plugin-toolkit@latest doctor --remote V1ki/dsh-plugin-subscriptions
|
|
1067
|
+
```
|
|
1068
|
+
|
|
1069
|
+
**Will a plugin install on the DSH version I run?**
|
|
1070
|
+
Add `--host <version>` to a remote audit. It prints `compatible`,
|
|
1071
|
+
`incompatible` or `unknown` against that host, and an `incompatible` result is
|
|
1072
|
+
counted as failing and exits `1`:
|
|
1073
|
+
|
|
1074
|
+
```sh
|
|
1075
|
+
npx dsh-plugin-toolkit@latest audit --remote L3n3L/dsh-resume --host 0.2.2-alpha.3
|
|
1076
|
+
```
|
|
1077
|
+
|
|
1078
|
+
**What should CI run?**
|
|
1079
|
+
The composite action's default `command` is `verify`, the only check that reads
|
|
1080
|
+
the tarball. Use `command: doctor` for a fast manifest-only gate, or
|
|
1081
|
+
`command: index` to audit the market index:
|
|
1082
|
+
|
|
1083
|
+
```yaml
|
|
1084
|
+
- uses: WJDdidi-1/dsh-plugin-toolkit@v1
|
|
1085
|
+
with:
|
|
1086
|
+
dir: plugin
|
|
1087
|
+
```
|
|
1088
|
+
|
|
1010
1089
|
## Changelog
|
|
1011
1090
|
|
|
1012
1091
|
[`CHANGELOG.md`](CHANGELOG.md) lists what changed in each release, including
|
|
@@ -1,10 +1,19 @@
|
|
|
1
1
|
# dsh-resume
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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 =
|
|
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 =
|
|
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. */
|
|
@@ -93,7 +93,36 @@ export function createLatencyFetch({
|
|
|
93
93
|
|
|
94
94
|
const SILENT = { log() {}, error() {} };
|
|
95
95
|
|
|
96
|
-
/**
|
|
96
|
+
/**
|
|
97
|
+
* Count the work an audit asks the fake GitHub to do. `active` is a request
|
|
98
|
+
* that has started and not answered; `maxInFlight` is the concurrency the
|
|
99
|
+
* audit actually reached, not the width it was given. Unlike wall clock, these
|
|
100
|
+
* counters do not change when the machine is slow or loaded.
|
|
101
|
+
*/
|
|
102
|
+
function countRequests(fetchImpl) {
|
|
103
|
+
let active = 0;
|
|
104
|
+
let maxInFlight = 0;
|
|
105
|
+
let requests = 0;
|
|
106
|
+
return {
|
|
107
|
+
fetchImpl: async (url) => {
|
|
108
|
+
requests += 1;
|
|
109
|
+
active += 1;
|
|
110
|
+
maxInFlight = Math.max(maxInFlight, active);
|
|
111
|
+
try {
|
|
112
|
+
return await fetchImpl(url);
|
|
113
|
+
} finally {
|
|
114
|
+
active -= 1;
|
|
115
|
+
}
|
|
116
|
+
},
|
|
117
|
+
stats: () => ({ requests, maxInFlight }),
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Time one audit of the whole list at a fixed width, and count the requests
|
|
123
|
+
* and the concurrency it actually used. The timing is context; the counters
|
|
124
|
+
* are the invariant a benchmark can assert on any machine.
|
|
125
|
+
*/
|
|
97
126
|
export async function measureAuditList({
|
|
98
127
|
targets,
|
|
99
128
|
jobs = DEFAULT_JOBS,
|
|
@@ -105,22 +134,28 @@ export async function measureAuditList({
|
|
|
105
134
|
if (Array.isArray(targets) === false || targets.length === 0) {
|
|
106
135
|
throw new Error('measureAuditList needs at least one target');
|
|
107
136
|
}
|
|
137
|
+
const counted = countRequests(fetchImpl);
|
|
108
138
|
const started = now();
|
|
109
|
-
const result = await auditRemoteTargets(targets.join(','), { fetchImpl, jobs, io });
|
|
139
|
+
const result = await auditRemoteTargets(targets.join(','), { fetchImpl: counted.fetchImpl, jobs, io });
|
|
110
140
|
const elapsedMs = now() - started;
|
|
141
|
+
const { requests, maxInFlight } = counted.stats();
|
|
111
142
|
return {
|
|
112
143
|
jobs,
|
|
113
144
|
targets: targets.length,
|
|
114
145
|
elapsedMs,
|
|
115
146
|
secondsPerRepository: elapsedMs / 1000 / targets.length,
|
|
147
|
+
requests,
|
|
148
|
+
maxInFlight,
|
|
116
149
|
result,
|
|
117
150
|
};
|
|
118
151
|
}
|
|
119
152
|
|
|
120
153
|
/**
|
|
121
154
|
* Run the same named list with one worker (the old loop) and with `jobs`
|
|
122
|
-
* workers (the default). The
|
|
123
|
-
*
|
|
155
|
+
* workers (the default). The reported speedup is wall clock, so it is context,
|
|
156
|
+
* not a guarantee: a loaded machine can make the wider run noisier. The
|
|
157
|
+
* measured work (`requests` and `maxInFlight`) is what batching does guarantee
|
|
158
|
+
* and what tests should assert.
|
|
124
159
|
*/
|
|
125
160
|
export async function runBenchmark({
|
|
126
161
|
list = BENCHMARK_LIST,
|
|
@@ -163,6 +198,7 @@ export function formatBenchmark(result, { root = ROOT } = {}) {
|
|
|
163
198
|
`benchmark: ${result.targets.length} repositories from ${list}, ${result.latencyMs} ms per API request`,
|
|
164
199
|
` before --jobs 1 ${(result.before.elapsedMs / 1000).toFixed(2)} s wall ${seconds(result.before.secondsPerRepository)}/repository`,
|
|
165
200
|
` after --jobs ${String(result.after.jobs).padEnd(10)} ${(result.after.elapsedMs / 1000).toFixed(2)} s wall ${seconds(result.after.secondsPerRepository)}/repository (default)`,
|
|
166
|
-
`
|
|
201
|
+
` requests ${result.before.requests} before, ${result.after.requests} after max in flight ${result.before.maxInFlight} before, ${result.after.maxInFlight} after`,
|
|
202
|
+
` speedup ${result.speedup.toFixed(2)}x (wall clock, context only)`,
|
|
167
203
|
].join('\n');
|
|
168
204
|
}
|
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,
|
|
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 =
|
|
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.
|
|
@@ -425,7 +426,7 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
425
426
|
let result;
|
|
426
427
|
|
|
427
428
|
if (options.log !== undefined) {
|
|
428
|
-
const logFile =
|
|
429
|
+
const logFile = resolvePath(options.log);
|
|
429
430
|
let log;
|
|
430
431
|
try {
|
|
431
432
|
log = fs.readFileSync(logFile, 'utf8');
|
|
@@ -467,7 +468,7 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
467
468
|
io.log(` fix: ${cause.fix}`);
|
|
468
469
|
}
|
|
469
470
|
if (checkout !== undefined) {
|
|
470
|
-
const report = doctor(
|
|
471
|
+
const report = doctor(resolvePath(checkout));
|
|
471
472
|
const { hits } = verdict(result, report.failures);
|
|
472
473
|
if (hits.length === 0) {
|
|
473
474
|
io.log(` in ${checkout}: none of those checks fail, so the cause is somewhere else`);
|
|
@@ -514,7 +515,12 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
514
515
|
}
|
|
515
516
|
|
|
516
517
|
if (command === 'index') {
|
|
517
|
-
const target =
|
|
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);
|
|
518
524
|
const index = readIndex(target);
|
|
519
525
|
let problems = 0;
|
|
520
526
|
for (const plugin of index.plugins ?? []) {
|
|
@@ -584,14 +590,19 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
584
590
|
}
|
|
585
591
|
return result.ok === true ? 0 : 1;
|
|
586
592
|
}
|
|
587
|
-
const result = await audit({
|
|
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
|
+
});
|
|
588
599
|
return result.ok === true ? 0 : 1;
|
|
589
600
|
}
|
|
590
601
|
|
|
591
602
|
if (command === 'dev') {
|
|
592
603
|
const { dev } = await import('./dev.mjs');
|
|
593
604
|
return dev({
|
|
594
|
-
dir:
|
|
605
|
+
dir: resolvePath(options.positional[0] ?? '.'),
|
|
595
606
|
dest: options.dest,
|
|
596
607
|
entry: options.entry,
|
|
597
608
|
build: options.build,
|
|
@@ -611,7 +622,7 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
611
622
|
}
|
|
612
623
|
const { mountClient } = await import('./testkit/index.mjs');
|
|
613
624
|
const panel = await mountClient({
|
|
614
|
-
file:
|
|
625
|
+
file: resolvePath(file),
|
|
615
626
|
slot: options.slot ?? 'sidebar.right.pane.tab',
|
|
616
627
|
surface: options.surface ?? 'sidebar',
|
|
617
628
|
});
|
|
@@ -628,7 +639,13 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
628
639
|
|
|
629
640
|
if (options.dryRun === true) {
|
|
630
641
|
io.log(`dry run: ${name}@${version}`);
|
|
631
|
-
const planned = plan({
|
|
642
|
+
const planned = plan({
|
|
643
|
+
dir,
|
|
644
|
+
version,
|
|
645
|
+
name,
|
|
646
|
+
tagPrefix: options.tagPrefix,
|
|
647
|
+
indexFile: options.index === undefined ? undefined : expandHome(options.index),
|
|
648
|
+
});
|
|
632
649
|
for (const step of planned.steps) {
|
|
633
650
|
io.log(` ${step.runs === false ? '·' : '→'} ${step.title}`);
|
|
634
651
|
io.log(` ${step.command}`);
|
|
@@ -643,8 +660,8 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
643
660
|
|
|
644
661
|
const result = await release({
|
|
645
662
|
dir,
|
|
646
|
-
indexFile: options.index,
|
|
647
|
-
marketDir: options.market,
|
|
663
|
+
indexFile: options.index === undefined ? undefined : expandHome(options.index),
|
|
664
|
+
marketDir: options.market === undefined ? undefined : resolvePath(options.market),
|
|
648
665
|
publish: options.publish === true,
|
|
649
666
|
tagPrefix: options.tagPrefix,
|
|
650
667
|
budgetMs: options.budget === undefined ? undefined : options.budget * 1000,
|