dsh-plugin-toolkit 0.20.20 → 0.20.22

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,36 @@
1
+ ## 0.20.22
2
+
3
+ - **A missing `audit --home` value is refused before the scan, and a later
4
+ `--home` cannot hide it.** The parser used to leave the missing path only in
5
+ the value slot, so a second `--home <dir>` overwrote the typo and the command
6
+ scanned anyway; every missing spelling is now recorded through the rest of
7
+ parsing. `audit --home`, `audit --home --timeout 50`, `audit --home --json`
8
+ and `audit --home --home <dir>` each exit `2` with `--home needs a directory
9
+ path` on stderr and no profile report on stdout, while `audit --home <dir>`
10
+ against the one-declared-plugin fixture still prints its `missing` row and
11
+ exits `1`. The README says a bare `--home` is a usage error, not a request to
12
+ scan `$HOME/.dsh` or a folder named after the next flag. A process-boundary
13
+ test spawns the shipped CLI for all three missing spellings and requires exit
14
+ `2` with no report, then runs the same binary against a checked-in clean home
15
+ and requires exit `0` with its `clean-plugin` row, so the refusal cannot pass
16
+ by breaking every scan.
17
+
18
+ ## 0.20.21
19
+
20
+ - **`doctor --fix --write` repairs a manifest saved with a UTF-8 BOM.** `doctor`
21
+ read the BOM away, but the repair write re-read the raw file with `JSON.parse`,
22
+ so it printed the planned `engines.dsh` edit and then failed with a bare
23
+ `Unexpected token` on the same manifest it had just accepted. Both repair
24
+ entry points (`doctor --fix` and `fix --engines`) now read through `doctor`'s
25
+ one BOM-aware manifest source, keep the existing indentation and line endings,
26
+ and write through one shared helper that starts from the BOM-stripped source,
27
+ so the rewritten file has no BOM (not a doubled one) and is valid JSON. A
28
+ write failure is now reported as a `manifest` failure by both commands instead
29
+ of escaping from `fix --engines`. Four process-level tests run the literal
30
+ `doctor . --fix --write` and `fix . --engines --write` from a temp plugin with
31
+ no `engines.dsh`: both repair a BOM copy and a no-BOM control, and both
32
+ normalize a doubled BOM without adding another one.
33
+
1
34
  ## 0.20.20
2
35
 
3
36
  - **A repeated `release --pr` is a no-op when the committed index already
package/README.md CHANGED
@@ -309,6 +309,12 @@ profile where the app silently skipped a plugin. It exits `0` when every
309
309
  installed plugin is loaded and valid. If no graph was read (`--host` omitted),
310
310
  the loaded column is `?` and only hard failures change the exit code.
311
311
 
312
+ `audit --home <dir>` scans a different profile home; both `~/.dsh` and
313
+ `~\.dsh` expand. A bare `--home`, or one followed by another flag such as
314
+ `--timeout 50` or `--json`, is a missing value rather than a request to scan
315
+ `$HOME/.dsh` or a folder literally named after the flag: the command exits `2`,
316
+ names `--home`, and prints no profile report.
317
+
312
318
  Without `--host` the loaded column is `?`, because guessing would be worse than
313
319
  saying nothing. Only packages that declare a `dsh` field are audited — the rest of
314
320
  `node_modules` is ordinary dependencies, and auditing those is noise.
@@ -1060,7 +1066,9 @@ npx dsh-plugin-toolkit@latest verify .
1060
1066
 
1061
1067
  **Will `doctor --fix` rewrite my `package.json`?**
1062
1068
  Only with `--write`. Without it the command prints the plan and stops; with it,
1063
- it applies the edits in the plan and runs the checks again.
1069
+ it applies the edits in the plan and runs the checks again. A manifest saved
1070
+ with a UTF-8 BOM is read and repaired through the same path, and the rewritten
1071
+ file no longer starts with the BOM; `fix --engines --write` uses that path too.
1064
1072
 
1065
1073
  **`doctor` passes, but the panel still does not appear. What next?**
1066
1074
  `doctor` checks the manifest and source without executing the plugin. `verify`
package/lib/audit.mjs CHANGED
@@ -11,7 +11,13 @@ import fs from 'node:fs';
11
11
  import os from 'node:os';
12
12
  import path from 'node:path';
13
13
 
14
- import { checkHostCompatibility, doctor, hostRange, version as manifestVersion } from './doctor.mjs';
14
+ import {
15
+ checkHostCompatibility,
16
+ doctor,
17
+ hostRange,
18
+ readManifestSource,
19
+ version as manifestVersion,
20
+ } from './doctor.mjs';
15
21
  import { hostCompatibility } from './compat.mjs';
16
22
  import { readGraph } from './dev.mjs';
17
23
  import { auditRemote, fixRemote } from './remote.mjs';
@@ -174,11 +180,10 @@ export function listInstalled({ home = DEFAULT_HOME } = {}) {
174
180
  }
175
181
  let manifest;
176
182
  try {
177
- // Strip the BOM the same way doctor does: a manifest saved by Notepad
178
- // is still readable, and treating it as unreadable would be a false
179
- // alarm in the other direction.
180
- const text = String(fs.readFileSync(manifestPath, 'utf8')).replace(/^\uFEFF/u, '').trim();
181
- manifest = JSON.parse(text);
183
+ // Read through the same BOM-aware path as doctor: a manifest saved
184
+ // by Notepad is still readable, and a parse failure keeps naming
185
+ // the file instead of only the JSON token.
186
+ manifest = readManifestSource(dir).manifest;
182
187
  } catch (error) {
183
188
  // A package.json that is listed in the profile but does not parse is
184
189
  // still an installed plugin, and "it does not parse" is exactly what
@@ -190,7 +195,7 @@ export function listInstalled({ home = DEFAULT_HOME } = {}) {
190
195
  name,
191
196
  profile,
192
197
  manifestPath,
193
- message: `${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
198
+ message: error instanceof Error ? error.message : String(error),
194
199
  }),
195
200
  );
196
201
  }
package/lib/cli.mjs CHANGED
@@ -194,9 +194,15 @@ function flags(argv) {
194
194
  // Like every other path flag: a bare `--home` is a missing path, not
195
195
  // permission to swallow the next option. Otherwise `audit --home
196
196
  // --timeout 50` would scan a folder literally named `--timeout` and
197
- // report "no plugins installed" with exit 0.
197
+ // report "no plugins installed" with exit 0. Remember the missing value
198
+ // apart from the value itself, so a later `--home <dir>` cannot overwrite
199
+ // it and turn the same typo into a real scan.
198
200
  const next = argv[index + 1];
199
- parsed.home = next === undefined || next.startsWith('--') === true ? '' : argv[++index];
201
+ if (next === undefined || next.startsWith('--') === true) {
202
+ parsed.homeMissing = true;
203
+ } else {
204
+ parsed.home = argv[++index];
205
+ }
200
206
  }
201
207
  else if (token === '--base') parsed.base = argv[++index];
202
208
  else if (token === '--market') parsed.market = argv[++index];
@@ -548,11 +554,14 @@ export async function run(argv, io = console, deps = {}) {
548
554
  }
549
555
 
550
556
  if (command === 'audit') {
551
- const { audit, parseJobs } = await import('./audit.mjs');
552
- if (options.home !== undefined && String(options.home).trim() === '') {
557
+ // Validate the home before importing the scanner, so a missing value is a
558
+ // usage error even if the scan module would have loaded or fallen back to
559
+ // `$HOME/.dsh` and printed a clean report.
560
+ if (options.homeMissing === true || (options.home !== undefined && String(options.home).trim() === '')) {
553
561
  io.error('dsh-plugin audit --home needs a directory path');
554
562
  return 2;
555
563
  }
564
+ const { audit, parseJobs } = await import('./audit.mjs');
556
565
  if (options.remote !== undefined || options.from !== undefined || options.patchDir !== undefined) {
557
566
  let remote = remoteTarget(options);
558
567
  let from = options.from;
package/lib/doctor.mjs CHANGED
@@ -55,7 +55,29 @@ function isRangeExpression(value) {
55
55
  return parseRange(value) !== null;
56
56
  }
57
57
 
58
- export function readManifest(dir) {
58
+ /**
59
+ * Remove every UTF-8 BOM at the start of a text file.
60
+ *
61
+ * One BOM is what Notepad writes; more than one is what a botched repair can
62
+ * leave behind. Stripping the run rather than a single character means a
63
+ * manifest that was already damaged is still readable, and a writer that starts
64
+ * from the stripped text cannot add another BOM on top.
65
+ */
66
+ export function stripBom(text) {
67
+ return String(text).replace(/^\uFEFF+/u, '');
68
+ }
69
+
70
+ /**
71
+ * Read the one local manifest every command reads.
72
+ *
73
+ * Notepad and some VS Code configurations save UTF-8 with a BOM. JSON.parse
74
+ * rejects it with a bare `Unexpected token`, so this is the single place that
75
+ * strips the BOM and names the file on failure. `raw` is the bytes as written:
76
+ * repair commands need it to keep the original indentation and line endings,
77
+ * and returning it here means the reader and the writer cannot disagree about
78
+ * which manifest is being edited.
79
+ */
80
+ export function readManifestSource(dir) {
59
81
  // `doctor '~/my-panel'` arrives with a literal tilde from cmd/PowerShell.
60
82
  // Resolve it here too, because this is also a public entry point.
61
83
  const target = resolvePath(dir);
@@ -63,16 +85,19 @@ export function readManifest(dir) {
63
85
  if (fs.existsSync(manifestPath) === false) {
64
86
  throw new Error(`no package.json in ${target}`);
65
87
  }
66
- // Notepad and some VS Code configurations save UTF-8 with a BOM. JSON.parse
67
- // rejects it with a bare `Unexpected token`, so strip it and name the file
68
- // on failure instead of leaving the user to guess which manifest broke.
69
- const text = String(fs.readFileSync(manifestPath, 'utf8')).replace(/^\uFEFF/u, '').trim();
88
+ const raw = String(fs.readFileSync(manifestPath, 'utf8'));
89
+ const text = stripBom(raw).trim();
70
90
  let manifest;
71
91
  try {
72
92
  manifest = JSON.parse(text);
73
93
  } catch (error) {
74
94
  throw new Error(`${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
75
95
  }
96
+ return { manifest, manifestPath, raw, target };
97
+ }
98
+
99
+ export function readManifest(dir) {
100
+ const { manifest, manifestPath } = readManifestSource(dir);
76
101
  return { manifest, manifestPath };
77
102
  }
78
103
 
package/lib/fix.mjs CHANGED
@@ -16,7 +16,7 @@ import fs from 'node:fs';
16
16
  import path from 'node:path';
17
17
 
18
18
  import { hostRangePlan, satisfiesRange } from './compat.mjs';
19
- import { checkHostRange, doctor, hostRange } from './doctor.mjs';
19
+ import { checkHostRange, doctor, hostRange, readManifestSource, stripBom } from './doctor.mjs';
20
20
  import { resolvePath } from './paths.mjs';
21
21
 
22
22
  /** The oldest host the toolkit itself supports, and the range `init` writes. */
@@ -147,12 +147,23 @@ function formatting(raw) {
147
147
  * prints is the edit the local command would make.
148
148
  */
149
149
  export function renderManifest(manifest, raw) {
150
- const { indent, eol, trailing } = formatting(raw);
150
+ const { indent, eol, trailing } = formatting(stripBom(raw));
151
151
  let text = JSON.stringify(manifest, null, indent);
152
152
  if (eol === '\r\n') text = text.replace(/\n/g, '\r\n');
153
153
  return `${text}${trailing}`;
154
154
  }
155
155
 
156
+ /**
157
+ * Write the one manifest both repair entry points edit.
158
+ *
159
+ * Rendering starts from the parsed JSON value and from the BOM-stripped source,
160
+ * so the BOM `readManifestSource` removed is never written back. Both commands
161
+ * use this helper, which keeps the no-doubled-BOM guarantee in one place.
162
+ */
163
+ function writeManifest({ manifestPath, manifest, raw }) {
164
+ fs.writeFileSync(manifestPath, renderManifest(manifest, raw));
165
+ }
166
+
156
167
  /** Split text for a diff without inventing a final empty line. */
157
168
  function diffLines(text) {
158
169
  const normalized = String(text).replace(/\r\n/gu, '\n');
@@ -266,10 +277,13 @@ export function fixEngines({ dir = '.', range, host, write = false, force = fals
266
277
  let raw;
267
278
  let manifest;
268
279
  try {
269
- raw = fs.readFileSync(manifestPath, 'utf8');
270
- manifest = JSON.parse(raw);
280
+ // Read through the same BOM-aware path `doctor` used to plan this edit.
281
+ // Parsing the raw file here would reject the very manifest the plan named.
282
+ const source = readManifestSource(target);
283
+ raw = source.raw;
284
+ manifest = source.manifest;
271
285
  } catch (error) {
272
- return failure('manifest', `cannot read ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
286
+ return failure('manifest', error instanceof Error ? error.message : String(error));
273
287
  }
274
288
  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest) === true) {
275
289
  return failure('manifest', `${manifestPath} does not hold a JSON object`);
@@ -296,12 +310,17 @@ export function fixEngines({ dir = '.', range, host, write = false, force = fals
296
310
  };
297
311
  }
298
312
 
299
- const content = renderManifest(planned.manifest, raw);
300
-
301
313
  let written = false;
302
314
  if (write === true) {
303
- fs.writeFileSync(manifestPath, content);
304
- written = true;
315
+ try {
316
+ writeManifest({ manifestPath, manifest: planned.manifest, raw });
317
+ written = true;
318
+ } catch (error) {
319
+ return failure(
320
+ 'manifest',
321
+ `cannot write ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`,
322
+ );
323
+ }
305
324
  }
306
325
 
307
326
  return {
@@ -477,10 +496,11 @@ export function doctorFix({ dir = '.', range, host, write = false, dryRun = fals
477
496
  const files = [];
478
497
  if (write === true && dryRun !== true && manifestEdits.length > 0) {
479
498
  try {
480
- const raw = fs.readFileSync(planned.manifestPath, 'utf8');
481
- const next = JSON.parse(raw);
482
- for (const entry of manifestEdits) setField(next, entry.field, entry.after);
483
- fs.writeFileSync(planned.manifestPath, renderManifest(next, raw));
499
+ // The plan was made from the BOM-aware read; use the same source here so
500
+ // a manifest `doctor` accepted is not rejected at write time.
501
+ const { raw, manifest } = readManifestSource(planned.dir);
502
+ for (const entry of manifestEdits) setField(manifest, entry.field, entry.after);
503
+ writeManifest({ manifestPath: planned.manifestPath, manifest, raw });
484
504
  files.push(planned.manifestPath);
485
505
  } catch (error) {
486
506
  return failure(
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.20",
3
+ "version": "0.20.22",
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": {