dsh-plugin-toolkit 0.20.10 → 0.20.12

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,49 @@
1
+ ## 0.20.12
2
+
3
+ - **`dsh-plugin fix <owner>/<repo> --remote` treats an already-correct range as
4
+ success.** When `package.json` already declares an `engines.dsh` range that
5
+ clears the check, the command still prints `ok engines.dsh is already
6
+ "<range>"; nothing to apply` but now exits `0` instead of `1`, matching the
7
+ local `fix --engines` no-op and the documented exit-code contract. No diff or
8
+ patch file is written.
9
+ - **The remote repair keeps its diff and error paths.** A manifest with no
10
+ `engines.dsh` still prints the unified diff and exits `0`; an invalid target
11
+ and a network or HTTP read failure still exit `2`; and the command writes no
12
+ local file unless `--patch` asks for one. Regression tests pin those paths
13
+ beside the already-correct no-op.
14
+ - **The remote repair exit codes are covered at the process boundary.** `npm
15
+ test` now spawns the real CLI for a remote manifest that is missing
16
+ `engines.dsh` and one that already declares a valid range, asserting exit
17
+ `0` for both. The README Exit codes table states the same contract.
18
+ - **A malformed `package.json` in an ordinary dependency still stays out of
19
+ `audit`.** The unreadable-manifest exception only applies when the package
20
+ name is in `dsh.profile.bundles`; a package that is neither declared there nor
21
+ readable enough to expose its `dsh` field is skipped as before, so a broken
22
+ transitive install does not turn every audit red.
23
+ - **A declared plugin with an unreadable `package.json` no longer disappears
24
+ from `audit`.** When an interrupted install leaves a truncated manifest, the
25
+ `dsh` field that marks the package as a plugin cannot be read. If the package
26
+ name is still listed in `dsh.profile.bundles`, `audit` now reports a
27
+ `manifest` failure naming the unreadable `package.json` and exits `1` instead
28
+ of skipping the folder as an ordinary dependency. Valid sibling plugins on the
29
+ same run are still listed.
30
+
31
+ ## 0.20.11
32
+
33
+ - **`audit --remote --from` carries the `--host` answer through the whole
34
+ batch.** Each repository is compared with the host you name even when
35
+ `--jobs` runs several audits at once, so the printed verdict and the `--json`
36
+ row carry the same `host` and `compatibility` fields, in input order,
37
+ whatever order the responses arrive in. With `--patch-dir`, a host-targeted
38
+ repair is written for a valid range that excludes the host, while a
39
+ repository that already accepts it is skipped.
40
+ - **The batch host mode is documented where the batch commands are.** `--help`
41
+ shows the `audit --remote --from <file> --host <version>` form, and the
42
+ README and repair guide explain that npm's pre-release rule applies — for
43
+ example, `>=0.2.0` does not accept `0.2.2-alpha.3` unless the range names a
44
+ pre-release of that same version. The semver edge cases are pinned by
45
+ regression tests.
46
+
1
47
  ## 0.20.10
2
48
 
3
49
  - **`expectSnapshot()` writes the baseline when `UPDATE_SNAPSHOTS=1`.** The
package/README.md CHANGED
@@ -311,6 +311,17 @@ Without `--host` the loaded column is `?`, because guessing would be worse than
311
311
  saying nothing. Only packages that declare a `dsh` field are audited — the rest of
312
312
  `node_modules` is ordinary dependencies, and auditing those is noise.
313
313
 
314
+ An installed package whose `package.json` cannot be read is the exception: the
315
+ `dsh` field that would mark it as a plugin is in the file that failed to parse.
316
+ If its name is still in `dsh.profile.bundles`, `audit` reports a `manifest`
317
+ failure naming the unreadable `package.json` and exits `1` instead of treating
318
+ the folder as an ordinary dependency. A truncated manifest from an interrupted
319
+ install therefore cannot make the plugin disappear from the report, and a valid
320
+ sibling plugin is still listed on the same run. The exception stays narrow: a
321
+ damaged `package.json` in a package that is neither in `dsh.profile.bundles` nor
322
+ readable enough to expose a `dsh` field is still an ordinary dependency and is
323
+ skipped, so one broken transitive install does not fail every audit.
324
+
314
325
  ## Edit a plugin that is already installed
315
326
 
316
327
  The host already swaps a rebuilt bundle without a page reload: it watches each plugin's entry artifact and reports a `rebuilt` frame on `/plugins/events`. `dev` puts the new file where the host is looking, then **proves** the frame arrived instead of asking you to check by eye.
@@ -458,8 +469,11 @@ The line carries the range `package.json` declares and one of `compatible`,
458
469
  `incompatible`, or `unknown` against that host version. `unknown` is the honest
459
470
  answer for a missing or malformed range — there is nothing to compare — while a
460
471
  range that excludes the host is `incompatible`, counted as failing, and exits
461
- `1`. The same flag works in the batch mode, so one `--from` run answers the
462
- whole list:
472
+ `1`. npm's pre-release rule is part of the answer: `>=0.2.0` does not accept
473
+ `0.2.2-alpha.3`, because a range only opts into a pre-release when it names one
474
+ of the same `major.minor.patch`. A canary host can therefore be `incompatible`
475
+ with a range that will accept the final release. The same flag works in the
476
+ batch mode, so one `--from` run answers the whole list:
463
477
 
464
478
  ```sh
465
479
  $ dsh-plugin audit --remote --from repos.txt --host 0.2.2-alpha.3
@@ -579,9 +593,12 @@ $ dsh-plugin audit --remote --from repos.txt --patch-dir repairs/
579
593
 
580
594
  It creates the directory and writes one `owner__repo.patch` for every
581
595
  repository whose `engines.dsh` check fails, with the same diff `fix --remote
582
- --patch` produces. Repositories that are clean, unreadable, or need a repair
583
- the tool cannot make automatically are skipped. The repository itself is still
584
- only read, and `--force` replaces a patch that is already there.
596
+ --patch` produces. With `--host <version>`, the repair is aimed at that host, so
597
+ a repository whose valid range merely excludes the host is repaired too; a
598
+ repository that already accepts the host is skipped even when it is in the same
599
+ batch. Repositories that are clean, unreadable, or need a repair the tool cannot
600
+ make automatically are skipped. The repository itself is still only read, and
601
+ `--force` replaces a patch that is already there.
585
602
 
586
603
  ### The 3 November list
587
604
 
@@ -766,6 +783,11 @@ dsh-plugin fix: would write engines.dsh ">=0.2.0" (was missing) in PrismLean/dsh
766
783
  remote repositories are read-only; nothing written; apply this diff in your checkout
767
784
  ```
768
785
 
786
+ When `package.json` already declares a range that clears the check, there is
787
+ nothing to apply: the command prints `ok engines.dsh is already "<range>";
788
+ nothing to apply` and exits `0`, the same no-op as `fix --engines` on a
789
+ checkout. No diff and no patch file is written.
790
+
769
791
  To apply it, clone the repository, save that diff with `--patch`, and apply it
770
792
  in the checkout:
771
793
 
@@ -968,9 +990,13 @@ merged
968
990
 
969
991
  | Code | Meaning |
970
992
  | --- | --- |
971
- | 0 | Done, or nothing to complain about |
993
+ | 0 | Done, or nothing to complain about — including `fix --remote` when `engines.dsh` is already a valid range |
972
994
  | 1 | A check failed, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
973
- | 2 | Unknown command |
995
+ | 2 | Unknown command, invalid usage, or a remote request that could not be completed |
996
+
997
+ `fix <owner>/<repo> --remote` exits `0` both when it prints a diff for a missing
998
+ `engines.dsh` and when the manifest already declares a range that clears the
999
+ check; the second case prints `ok ... nothing to apply` and writes no diff.
974
1000
 
975
1001
  ## What is not here yet
976
1002
 
package/lib/audit.mjs CHANGED
@@ -91,6 +91,24 @@ export function explainNotLoaded({ manifest, name, profileFile, bundles = [] } =
91
91
  };
92
92
  }
93
93
 
94
+ /**
95
+ * A package whose `package.json` cannot be read is normally indistinguishable
96
+ * from an ordinary dependency, because the `dsh` field that marks a plugin lives
97
+ * in the file that failed to parse. The profile's `dsh.profile.bundles` list is
98
+ * the other record of what the user installed, so it is what lets an
99
+ * interrupted install be reported instead of disappearing from the audit.
100
+ */
101
+ function unreadableInstalled({ dir, name, profile, manifestPath, message }) {
102
+ return {
103
+ dir,
104
+ manifest: { name },
105
+ profile,
106
+ manifestPath,
107
+ unreadable: true,
108
+ error: message,
109
+ };
110
+ }
111
+
94
112
  /** Every package folder inside every profile, scoped names included. */
95
113
  export function listInstalled({ home = DEFAULT_HOME } = {}) {
96
114
  const profiles = path.join(home, 'profiles');
@@ -99,21 +117,73 @@ export function listInstalled({ home = DEFAULT_HOME } = {}) {
99
117
  for (const profile of fs.readdirSync(profiles).sort()) {
100
118
  const modules = path.join(profiles, profile, 'node_modules');
101
119
  if (fs.existsSync(modules) === false) continue;
120
+ const declared = new Set(readProfileBundles({ home, profile }).bundles);
102
121
  for (const entry of fs.readdirSync(modules).sort()) {
103
122
  if (entry.startsWith('.') === true) continue;
104
123
  const candidates = entry.startsWith('@')
105
- ? fs.readdirSync(path.join(modules, entry)).sort().map((name) => path.join(modules, entry, name))
106
- : [path.join(modules, entry)];
107
- for (const dir of candidates) {
124
+ ? fs
125
+ .readdirSync(path.join(modules, entry))
126
+ .sort()
127
+ .map((name) => ({ dir: path.join(modules, entry, name), name: `${entry}/${name}` }))
128
+ : [{ dir: path.join(modules, entry), name: entry }];
129
+ for (const { dir, name } of candidates) {
130
+ // A broken package.json is only evidence of a plugin when the profile
131
+ // says it mounts that name. Without that record an ordinary dependency
132
+ // whose install was interrupted must stay out of the audit, or one bad
133
+ // transitive package would turn every profile red.
134
+ const listedInProfile = declared.has(name) === true;
108
135
  const manifestPath = path.join(dir, 'package.json');
109
- if (fs.existsSync(manifestPath) === false) continue;
136
+ if (fs.existsSync(manifestPath) === false) {
137
+ if (listedInProfile === true) {
138
+ found.push(
139
+ unreadableInstalled({
140
+ dir,
141
+ name,
142
+ profile,
143
+ manifestPath,
144
+ message: `${manifestPath} is missing, so the installed copy has no manifest to read`,
145
+ }),
146
+ );
147
+ }
148
+ continue;
149
+ }
110
150
  let manifest;
111
151
  try {
112
- manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
113
- } catch {
114
- // A package.json that does not parse is still an installed plugin, and
115
- // "it does not parse" is exactly what the author needs to hear.
116
- manifest = { name: path.basename(dir) };
152
+ // Strip the BOM the same way doctor does: a manifest saved by Notepad
153
+ // is still readable, and treating it as unreadable would be a false
154
+ // alarm in the other direction.
155
+ const text = String(fs.readFileSync(manifestPath, 'utf8')).replace(/^\uFEFF/u, '').trim();
156
+ manifest = JSON.parse(text);
157
+ } catch (error) {
158
+ // A package.json that is listed in the profile but does not parse is
159
+ // still an installed plugin, and "it does not parse" is exactly what
160
+ // the author needs to hear.
161
+ if (listedInProfile === true) {
162
+ found.push(
163
+ unreadableInstalled({
164
+ dir,
165
+ name,
166
+ profile,
167
+ manifestPath,
168
+ message: `${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
169
+ }),
170
+ );
171
+ }
172
+ continue;
173
+ }
174
+ if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest) === true) {
175
+ if (listedInProfile === true) {
176
+ found.push(
177
+ unreadableInstalled({
178
+ dir,
179
+ name,
180
+ profile,
181
+ manifestPath,
182
+ message: `${manifestPath} is readable JSON but not a package object, so its dsh field cannot be checked`,
183
+ }),
184
+ );
185
+ }
186
+ continue;
117
187
  }
118
188
  // Only packages that declare themselves as plugins. node_modules is full
119
189
  // of ordinary dependencies, and auditing those is noise.
@@ -463,6 +533,10 @@ export async function auditRemoteTargets(
463
533
  ref,
464
534
  readErrors: 'note',
465
535
  rateLimitState,
536
+ // Keep the host answer on the report itself as well as the printed row.
537
+ // A batch may schedule this read beside other repositories, but the
538
+ // compatibility verdict must not depend on which worker finished first.
539
+ ...(hostVersion === '' ? {} : { host: hostVersion }),
466
540
  });
467
541
  row = remoteFinding(report, hostVersion);
468
542
  manifestText = report.raw;
@@ -660,16 +734,27 @@ export async function audit({
660
734
  }
661
735
 
662
736
  const profileFiles = new Map();
663
- const rows = installed.map(({ dir, manifest, profile }) => {
737
+ const rows = installed.map(({ dir, manifest, profile, manifestPath, unreadable = false, error }) => {
664
738
  let failures;
665
- try {
666
- ({ failures } = doctor(dir, { installed: true }));
667
- } catch (error) {
668
- failures = [{ check: 'manifest', message: error.message }];
739
+ if (unreadable === true) {
740
+ // doctor would throw on the same file; keep the read error the install
741
+ // scan already recorded so the row names the unreadable package.json.
742
+ failures = [{ check: 'manifest', message: error }];
743
+ } else {
744
+ try {
745
+ ({ failures } = doctor(dir, { installed: true }));
746
+ } catch (caught) {
747
+ failures = [{ check: 'manifest', message: caught.message }];
748
+ }
669
749
  }
670
750
  const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
671
751
  let explanation = null;
672
- if (loaded === false) {
752
+ if (unreadable === true) {
753
+ explanation = {
754
+ reason: `${manifestPath} is unreadable, so the loader cannot tell what to mount`,
755
+ action: `reinstall ${manifest.name} so its package.json is written completely`,
756
+ };
757
+ } else if (loaded === false) {
673
758
  if (profileFiles.has(profile) === false) {
674
759
  profileFiles.set(profile, readProfileBundles({ home, profile }));
675
760
  }
@@ -689,6 +774,7 @@ export async function audit({
689
774
  failures,
690
775
  ...split(failures),
691
776
  loaded,
777
+ unreadable: unreadable === true,
692
778
  reason: explanation?.reason ?? null,
693
779
  action: explanation?.action ?? null,
694
780
  };
@@ -697,11 +783,12 @@ export async function audit({
697
783
  const width = Math.max(...rows.map((row) => row.name.length), 6);
698
784
  const detailIndent = ' '.repeat(width + 24);
699
785
  for (const row of rows) {
700
- const state = row.loaded === null ? '?' : row.loaded === true ? 'loaded' : 'not loaded';
701
- const reason = row.loaded === false ? ` — ${row.reason}` : '';
786
+ const state =
787
+ row.unreadable === true ? 'unreadable' : row.loaded === null ? '?' : row.loaded === true ? 'loaded' : 'not loaded';
788
+ const reason = row.loaded === false || row.unreadable === true ? ` — ${row.reason}` : '';
702
789
  io.log(`${row.name.padEnd(width)} ${String(row.version).padEnd(8)} ${state.padEnd(10)} ${describe(row)}${reason}`);
703
790
  for (const failure of row.failures) io.log(`${' '.repeat(width + 22)}${failure.check}: ${failure.message}`);
704
- if (row.loaded === false) io.log(`${detailIndent}fix: ${row.action}`);
791
+ if (row.loaded === false || row.unreadable === true) io.log(`${detailIndent}fix: ${row.action}`);
705
792
  }
706
793
 
707
794
  const failed = rows.filter((row) => row.hard.length > 0);
package/lib/cli.mjs CHANGED
@@ -67,6 +67,9 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
67
67
  dsh-plugin audit --remote --from <file> --patch-dir <dir> save one repair per repository
68
68
  dsh-plugin audit --remote --from repos.txt --patch-dir repairs/
69
69
 
70
+ dsh-plugin audit --remote --from <file> --host <version> will every range accept the host you run?
71
+ dsh-plugin audit --remote --from repos.txt --host 0.2.2-alpha.3
72
+
70
73
  dsh-plugin audit --remote <list> --json machine-readable findings for owner/repo,owner/repo
71
74
  dsh-plugin audit --remote V1ki/dsh-plugin-subscriptions,demo/plugin --json
72
75
 
@@ -355,9 +358,12 @@ export async function run(argv, io = console, deps = {}) {
355
358
  return 2;
356
359
  }
357
360
  if (result.changed !== true) {
361
+ // A manifest that already declares a range clearing the check is a
362
+ // successful repair plan, exactly like the local `fix --engines` no-op:
363
+ // there is no failure to report, so the documented exit code is 0.
358
364
  io.log(`ok engines.dsh is already "${result.range}"; nothing to apply`);
359
365
  if (typeof result.why === 'string' && result.why.length > 0) io.log(` ${result.why}`);
360
- return 1;
366
+ return 0;
361
367
  }
362
368
  const was = result.before === null ? 'missing' : `"${result.before}"`;
363
369
  io.log(`dsh-plugin fix: would write engines.dsh "${result.range}" (was ${was}) in ${result.target.slug}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.10",
3
+ "version": "0.20.12",
4
4
  "description": "Preflight, release and test DeepSeek Harness plugins: check a folder or any GitHub repository, wait for npm to actually serve the version, and keep the market index honest.",
5
5
  "type": "module",
6
6
  "bin": {