dsh-plugin-toolkit 0.20.26 → 0.20.27

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,42 @@
1
+ ## 0.20.27
2
+
3
+ - **`fix --remote` reads a `package.json` saved with a UTF-8 BOM, so the host
4
+ range can be aimed at the install that failed.** The remote reader passed the
5
+ BOM straight to `JSON.parse`, which threw; `fix --remote --engines --host 0.3.0`
6
+ exited `2` and `audit --remote` reported the manifest as invalid JSON, while
7
+ the local fixer repaired the same file. The remote reader now strips the BOM
8
+ through the same helper `doctor` uses, the planned diff removes it, and the
9
+ applied patch writes the host range without putting it back. A regression test
10
+ applies the remote patch to a BOM checkout and checks that the written
11
+ `>=0.3.0 <1.0.0` accepts `0.3.0` and rejects `1.0.0`.
12
+
13
+ - **A requested app graph that cannot be read now fails the audit instead of
14
+ passing it.** `audit --host` logged `could not read the plugin graph: fetch
15
+ failed` and then exited `0` with a clean `?` row, so the documented CI gate
16
+ passed without observing which plugins the running app loaded. The command now
17
+ names the `/plugins/events` URL that failed, prints no plugin rows or clean
18
+ summary, and exits `2`; an audit without `--host` still exits `0` with `?` and
19
+ only hard failures change the exit code. A CLI regression runs the closed
20
+ `127.0.0.1:9` control and requires the `--host` run to exit `2` while the
21
+ same profile without it stays clean.
22
+
23
+ - **`audit --remote --host` refuses a missing value instead of silently
24
+ dropping the compatibility answer.** A bare `--host` left the host unset, so
25
+ the command printed an audit without the comparison the user asked for, and
26
+ `--host --json` consumed `--json` as a version and compared every repository
27
+ against the literal text `--json`. A following option or the end of the line
28
+ is now a missing value: the CLI exits `2`, names the flag, and reads neither
29
+ GitHub nor a `--from` file. `fix --host` gets the same guard, so a bare flag
30
+ cannot fall back to planning the default range. Tests pin the bare flag,
31
+ `--host --json`, a missing `--from` file, a local `fix`, a valid control, and
32
+ the process boundary.
33
+
34
+ - **Caret and tilde ranges on a wildcard major match npm's `*`.** `^*`, `~x`
35
+ and `~>*` are valid npm ranges that accept every stable host; the
36
+ compatibility parser called them malformed and answered `unknown`. They now
37
+ expand to any version, with the same pre-release exclusion npm applies, so
38
+ `audit --remote --host` and `doctor` agree with the installer.
39
+
1
40
  ## 0.20.26
2
41
 
3
42
  - **The published tarball ships `scripts/preview.mjs`, so the command the
package/README.md CHANGED
@@ -306,8 +306,12 @@ that is actually broken.
306
306
  `audit` exits `1` when an installed plugin has a hard failure **or** when the
307
307
  running app did not load at least one installed plugin, so CI can gate on a
308
308
  profile where the app silently skipped a plugin. It exits `0` when every
309
- installed plugin is loaded and valid. If no graph was read (`--host` omitted),
310
- the loaded column is `?` and only hard failures change the exit code.
309
+ installed plugin is loaded and valid. When `--host` is given but the app cannot
310
+ be reached, the command has not observed the graph it was asked for: it prints
311
+ the `/plugins/events` URL it could not read, prints no plugin rows or clean
312
+ summary, and exits `2` so a CI gate cannot pass against an unreachable app.
313
+ Without `--host`, the loaded column is `?` and only hard failures change the
314
+ exit code.
311
315
 
312
316
  `audit --home <dir>` scans a different profile home; both `~/.dsh` and
313
317
  `~\.dsh` expand. A bare `--home`, or one followed by another flag such as
@@ -514,6 +518,9 @@ the DSH version to compare against, and `--json` for the machine-readable
514
518
  finding. `--jobs <n>` sets the batch width, and `--patch-dir <dir>` writes the
515
519
  host-targeted repair for each repository that needs one. The help text lists
516
520
  the same flags; a test fails if this section names a flag the CLI does not have.
521
+ A bare `--host` is a usage error, not an audit without the comparison: the
522
+ command exits `2` before it reads GitHub, and `--host --json` does not consume
523
+ the `--json` flag as a version.
517
524
 
518
525
  `--host` still names the running app URL for a local `audit`; on `--remote` it
519
526
  is the DSH version to compare against. With `--json`, each finding gains
@@ -845,7 +852,8 @@ is still untouched. The same host-aware plan works with `--patch`:
845
852
  `fix <owner>/<repo> --remote --engines --host 0.3.0 --patch repair.patch` plans
846
853
  `>=0.3.0 <1.0.0` and prints why. After cloning, `fix . --engines --host 0.3.0
847
854
  --write` applies that same range; either path writes one that accepts the host
848
- and rejects the next major. `audit --remote --host <version> --patch-dir <dir>`
855
+ and rejects the next major. The remote reader strips a UTF-8 BOM, so a manifest
856
+ saved on Windows gives the same plan and the patch removes the BOM too. `audit --remote --host <version> --patch-dir <dir>`
849
857
  writes host-targeted repairs for a whole list. `git apply --check` is the dry
850
858
  run: it fails before changing anything if the manifest moved since the diff was
851
859
  printed. Commit the applied change as you would any other edit.
package/lib/audit.mjs CHANGED
@@ -768,16 +768,25 @@ export async function audit({
768
768
  host,
769
769
  });
770
770
  }
771
- const installed = listInstalled({ home });
772
- if (installed.length === 0) {
773
- io.log('no plugins installed in any profile (a plugin declares a "dsh" field)');
774
- return { ok: true, plugins: [], graph: null };
775
- }
776
-
777
771
  let graph = null;
778
772
  if (typeof host === 'string' && host.length > 0) {
779
773
  graph = await readGraph({ host, timeoutMs, fetchImpl });
780
- if (graph.ok !== true) io.log(`could not read the plugin graph: ${graph.reason}`);
774
+ if (graph.ok !== true) {
775
+ // A requested graph that could not be read is not the same as an audit
776
+ // without a graph. The caller asked which plugins the running app
777
+ // loaded, and the command observed nothing; exiting 0 would let a CI gate
778
+ // pass while the app was unreachable. The reason names the exact
779
+ // `/plugins/events` URL that could not be read, and returning before the
780
+ // rows keeps a valid plugin from looking like a clean result.
781
+ io.log(`could not read the plugin graph: ${graph.reason}`);
782
+ return { ok: false, exitCode: 2, plugins: [], graph };
783
+ }
784
+ }
785
+
786
+ const installed = listInstalled({ home });
787
+ if (installed.length === 0) {
788
+ io.log('no plugins installed in any profile (a plugin declares a "dsh" field)');
789
+ return { ok: true, plugins: [], graph };
781
790
  }
782
791
 
783
792
  const profileFiles = new Map();
package/lib/cli.mjs CHANGED
@@ -155,7 +155,18 @@ function flags(argv) {
155
155
  else if (token === '--dest') parsed.dest = argv[++index];
156
156
  else if (token === '--entry') parsed.entry = argv[++index];
157
157
  else if (token === '--build') parsed.build = argv[++index];
158
- else if (token === '--host') parsed.host = argv[++index];
158
+ else if (token === '--host') {
159
+ // A bare `--host` is a missing value, not permission to swallow the next
160
+ // flag. `audit --remote --host --json` used to compare every repository
161
+ // against the literal version `--json` instead of printing JSON; the
162
+ // audit branch reports the missing value before any repository is read.
163
+ const next = argv[index + 1];
164
+ if (next === undefined || next.startsWith('--') === true) {
165
+ parsed.hostMissing = true;
166
+ } else {
167
+ parsed.host = argv[++index];
168
+ }
169
+ }
159
170
  else if (token === '--jobs') {
160
171
  // A missing value is invalid, not a silent fall back to the default; the
161
172
  // audit branch names the flag in the error.
@@ -243,6 +254,22 @@ export async function run(argv, io = console, deps = {}) {
243
254
  return 0;
244
255
  }
245
256
 
257
+ // `--host` means a URL for a local audit and a DSH version for a remote one,
258
+ // so a bare flag must stop before either reads anything. Otherwise the audit
259
+ // silently omits the compatibility answer the user asked for.
260
+ if (options.hostMissing === true || (options.host !== undefined && String(options.host).trim() === '')) {
261
+ const hint =
262
+ command === 'audit'
263
+ ? 'the running app URL, or the DSH version with --remote'
264
+ : command === 'fix'
265
+ ? 'the DSH version to aim at'
266
+ : command === 'dev'
267
+ ? 'the app URL'
268
+ : 'a value';
269
+ io.error(`dsh-plugin ${command} --host needs ${hint}`);
270
+ return 2;
271
+ }
272
+
246
273
  if (command === 'doctor' && options.remote !== undefined) {
247
274
  if (options.fix === true) {
248
275
  io.error('dsh-plugin doctor --fix: --remote is read-only, so it cannot repair; run --fix against a checkout');
@@ -618,7 +645,9 @@ export async function run(argv, io = console, deps = {}) {
618
645
  timeoutMs: options.timeout,
619
646
  io,
620
647
  });
621
- return result.ok === true ? 0 : 1;
648
+ // A requested graph that could not be read is an operational failure, not
649
+ // an audit finding: exit 2 so CI cannot treat an unreachable app as clean.
650
+ return result.exitCode ?? (result.ok === true ? 0 : 1);
622
651
  }
623
652
 
624
653
  if (command === 'dev') {
package/lib/compat.mjs CHANGED
@@ -205,11 +205,13 @@ function expandToken(token) {
205
205
  const partial = parsePartialVersion(body);
206
206
  if (partial === null) return null;
207
207
  if (operator === '^') {
208
- if (partial.major === null) return null;
208
+ // npm normalises `^*` (and `^x`) to `*`: there is no major boundary to
209
+ // begin a caret line from, so the range accepts every stable version.
210
+ if (partial.major === null) return [];
209
211
  return caretBounds(partial);
210
212
  }
211
213
  if (operator === '~' || operator === '~>') {
212
- if (partial.major === null) return null;
214
+ if (partial.major === null) return [];
213
215
  return tildeBounds(partial);
214
216
  }
215
217
  if (operator === '=') return plainBounds(partial);
package/lib/dev.mjs CHANGED
@@ -135,7 +135,7 @@ export async function readGraph({ host, timeoutMs = 3000, fetchImpl = fetch }) {
135
135
  const url = `${String(host).replace(/\/+$/, '')}/plugins/events`;
136
136
  try {
137
137
  const response = await fetchImpl(url, { headers: { accept: 'text/event-stream' }, signal: controller.signal });
138
- if (response.ok !== true) return { ok: false, reason: `GET ${url} answered ${response.status}` };
138
+ if (response.ok !== true) return { ok: false, url, reason: `GET ${url} answered ${response.status}` };
139
139
  const reader = response.body.getReader();
140
140
  const decoder = new TextDecoder();
141
141
  let buffer = '';
@@ -155,13 +155,13 @@ export async function readGraph({ host, timeoutMs = 3000, fetchImpl = fetch }) {
155
155
  continue;
156
156
  }
157
157
  if (payload.type !== 'graph' || Array.isArray(payload.graph?.entries) === false) continue;
158
- return { ok: true, ids: new Set(payload.graph.entries.map((entry) => entry.id)) };
158
+ return { ok: true, url, ids: new Set(payload.graph.entries.map((entry) => entry.id)) };
159
159
  }
160
160
  }
161
- return { ok: false, reason: 'the stream ended before a graph frame arrived' };
161
+ return { ok: false, url, reason: `GET ${url} ended before a graph frame arrived` };
162
162
  } catch (error) {
163
- if (error.name === 'AbortError') return { ok: false, reason: `no graph frame within ${timeoutMs}ms` };
164
- return { ok: false, reason: error.message };
163
+ if (error.name === 'AbortError') return { ok: false, url, reason: `GET ${url} sent no graph frame within ${timeoutMs}ms` };
164
+ return { ok: false, url, reason: `GET ${url}: ${error.message}` };
165
165
  } finally {
166
166
  clearTimeout(timer);
167
167
  controller.abort();
package/lib/remote.mjs CHANGED
@@ -29,6 +29,7 @@ import {
29
29
  exportsApply,
30
30
  hostRange,
31
31
  rootEntry,
32
+ stripBom,
32
33
  } from './doctor.mjs';
33
34
  import { planEnginesEdit, renderManifest, unifiedDiff } from './fix.mjs';
34
35
  import { parseTarget as classifyTarget } from './github.mjs';
@@ -342,7 +343,10 @@ export async function auditRemote(
342
343
  }
343
344
  let manifest;
344
345
  try {
345
- manifest = JSON.parse(raw);
346
+ // GitHub serves the bytes as written. A manifest saved by Notepad starts
347
+ // with a BOM, which JSON.parse rejects; the local reader already strips it,
348
+ // so the remote verdict has to read the same file the same way.
349
+ manifest = JSON.parse(stripBom(raw));
346
350
  } catch (error) {
347
351
  fail('manifest', `package.json at ${slug} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
348
352
  return withHost({
@@ -523,7 +527,9 @@ export async function fixRemote(
523
527
 
524
528
  let manifest;
525
529
  try {
526
- manifest = JSON.parse(raw);
530
+ // Same BOM-aware read as `doctor` and audit: the remote manifest can be the
531
+ // one a Windows editor saved, and `fix --host` must not refuse to plan it.
532
+ manifest = JSON.parse(stripBom(raw));
527
533
  } catch (error) {
528
534
  throw new Error(
529
535
  `package.json at ${parsed.slug} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.26",
3
+ "version": "0.20.27",
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": {