dsh-plugin-toolkit 0.20.26 → 0.20.28
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 +50 -0
- package/README.md +11 -3
- package/lib/audit.mjs +16 -7
- package/lib/cli.mjs +31 -2
- package/lib/compat.mjs +4 -2
- package/lib/dev.mjs +5 -5
- package/lib/doctor.mjs +6 -2
- package/lib/remote.mjs +8 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,53 @@
|
|
|
1
|
+
## 0.20.28
|
|
2
|
+
|
|
3
|
+
- **`doctor` reads a README saved with a UTF-8 BOM instead of calling its
|
|
4
|
+
Requirements section missing.** A file written by Notepad starts with U+FEFF,
|
|
5
|
+
so a README whose first line is `## Requirements` began with the marker
|
|
6
|
+
rather than `#`; both the local and `--remote` check reported `README.md has
|
|
7
|
+
no Requirements section` even though it was there. The shared README reader
|
|
8
|
+
now strips the BOM through the same helper the manifest reader uses, while a
|
|
9
|
+
BOM README without the heading still fails. Tests pin the local and remote
|
|
10
|
+
first-line cases and the missing-heading control.
|
|
11
|
+
|
|
12
|
+
## 0.20.27
|
|
13
|
+
|
|
14
|
+
- **`fix --remote` reads a `package.json` saved with a UTF-8 BOM, so the host
|
|
15
|
+
range can be aimed at the install that failed.** The remote reader passed the
|
|
16
|
+
BOM straight to `JSON.parse`, which threw; `fix --remote --engines --host 0.3.0`
|
|
17
|
+
exited `2` and `audit --remote` reported the manifest as invalid JSON, while
|
|
18
|
+
the local fixer repaired the same file. The remote reader now strips the BOM
|
|
19
|
+
through the same helper `doctor` uses, the planned diff removes it, and the
|
|
20
|
+
applied patch writes the host range without putting it back. A regression test
|
|
21
|
+
applies the remote patch to a BOM checkout and checks that the written
|
|
22
|
+
`>=0.3.0 <1.0.0` accepts `0.3.0` and rejects `1.0.0`.
|
|
23
|
+
|
|
24
|
+
- **A requested app graph that cannot be read now fails the audit instead of
|
|
25
|
+
passing it.** `audit --host` logged `could not read the plugin graph: fetch
|
|
26
|
+
failed` and then exited `0` with a clean `?` row, so the documented CI gate
|
|
27
|
+
passed without observing which plugins the running app loaded. The command now
|
|
28
|
+
names the `/plugins/events` URL that failed, prints no plugin rows or clean
|
|
29
|
+
summary, and exits `2`; an audit without `--host` still exits `0` with `?` and
|
|
30
|
+
only hard failures change the exit code. A CLI regression runs the closed
|
|
31
|
+
`127.0.0.1:9` control and requires the `--host` run to exit `2` while the
|
|
32
|
+
same profile without it stays clean.
|
|
33
|
+
|
|
34
|
+
- **`audit --remote --host` refuses a missing value instead of silently
|
|
35
|
+
dropping the compatibility answer.** A bare `--host` left the host unset, so
|
|
36
|
+
the command printed an audit without the comparison the user asked for, and
|
|
37
|
+
`--host --json` consumed `--json` as a version and compared every repository
|
|
38
|
+
against the literal text `--json`. A following option or the end of the line
|
|
39
|
+
is now a missing value: the CLI exits `2`, names the flag, and reads neither
|
|
40
|
+
GitHub nor a `--from` file. `fix --host` gets the same guard, so a bare flag
|
|
41
|
+
cannot fall back to planning the default range. Tests pin the bare flag,
|
|
42
|
+
`--host --json`, a missing `--from` file, a local `fix`, a valid control, and
|
|
43
|
+
the process boundary.
|
|
44
|
+
|
|
45
|
+
- **Caret and tilde ranges on a wildcard major match npm's `*`.** `^*`, `~x`
|
|
46
|
+
and `~>*` are valid npm ranges that accept every stable host; the
|
|
47
|
+
compatibility parser called them malformed and answered `unknown`. They now
|
|
48
|
+
expand to any version, with the same pre-release exclusion npm applies, so
|
|
49
|
+
`audit --remote --host` and `doctor` agree with the installer.
|
|
50
|
+
|
|
1
51
|
## 0.20.26
|
|
2
52
|
|
|
3
53
|
- **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.
|
|
310
|
-
the
|
|
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.
|
|
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)
|
|
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')
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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:
|
|
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/doctor.mjs
CHANGED
|
@@ -184,13 +184,17 @@ export function checkHostCompatibility(manifest, hostVersion) {
|
|
|
184
184
|
* same repository.
|
|
185
185
|
*/
|
|
186
186
|
export function checkReadmeText(text, manifest) {
|
|
187
|
-
|
|
187
|
+
// A README saved by Notepad starts with a BOM, which would sit between the
|
|
188
|
+
// start of the file and a first-line `## Requirements` heading. The heading
|
|
189
|
+
// is there; strip the marker before deciding it is not.
|
|
190
|
+
const readme = stripBom(text);
|
|
191
|
+
if (/^#{1,3}\s*Requirements/im.test(readme) === false) {
|
|
188
192
|
return 'README.md has no Requirements section, so users cannot tell which host it needs';
|
|
189
193
|
}
|
|
190
194
|
const range = hostRange(manifest);
|
|
191
195
|
// ">= 0.2.0" and ">=0.2.0" are the same range; authors write both.
|
|
192
196
|
const squeeze = (value) => value.replace(/\s+/g, '');
|
|
193
|
-
if (range !== null && squeeze(
|
|
197
|
+
if (range !== null && squeeze(readme).includes(squeeze(range)) === false) {
|
|
194
198
|
return `README.md does not mention the host range "${range}" it declares`;
|
|
195
199
|
}
|
|
196
200
|
return null;
|
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
|
|
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
|
|
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.
|
|
3
|
+
"version": "0.20.28",
|
|
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": {
|