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 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. 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,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
- Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged.
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` and the
754
- files it points at through the GitHub API and prints the same verdict it would
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`, and
805
- `audit --remote --host <version> --patch-dir <dir>` writes host-targeted repairs
806
- for a whole list. `git apply --check` is the dry run: it fails before changing
807
- anything if the manifest moved since the diff was printed. Commit the applied
808
- change as you would any other edit.
809
-
810
- Then run `npx dsh-plugin-toolkit@latest doctor .` in the checkout. A checkout
811
- also reads the README text, so it can name a follow-up the remote read could
812
- not see — for `PrismLean/dsh-run-guard`, the README still has no Requirements
813
- section. [Repair a failed
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 is pushed,
816
- `doctor --remote PrismLean/dsh-run-guard` no longer reports `engines.dsh`. If
817
- the diff does not apply because the file changed, run the remote fixer again —
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
- `--log ~\.dsh\logs\install.log` expands exactly like
871
- `--log ~/.dsh/logs/install.log`. A log that cannot be read exits `2` and names
872
- the resolved absolute path it tried, never a directory literally named `~`.
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
- 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. */
@@ -93,7 +93,36 @@ export function createLatencyFetch({
93
93
 
94
94
  const SILENT = { log() {}, error() {} };
95
95
 
96
- /** Time one audit of the whole list at a fixed width. */
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 ratio is wall clock, so it includes the cost of
123
- * filling the last partial wave instead of only dividing by the worker count.
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
- ` speedup ${result.speedup.toFixed(2)}x`,
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, 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.
@@ -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 = path.resolve(expandHome(options.log));
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(path.resolve(checkout));
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 = 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);
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({ 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
+ });
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: path.resolve(options.positional[0] ?? '.'),
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: path.resolve(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({ 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
+ });
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,