dsh-plugin-toolkit 0.20.33 → 0.20.34

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,43 @@
1
+ ## 0.20.34
2
+
3
+ - **`audit --remote` names every finding the same way and never reads a
4
+ failed request as clean.** A batch given GitHub URLs reported the rows it had
5
+ read as `owner/repo` but kept the URL for rows skipped after a rate limit, so
6
+ a consumer joining findings saw two shapes for one list. Every target is now
7
+ normalised through the same parser. A read that fails for a reason other than
8
+ the quota (an HTTP 500 or a network error) is reported as `unreadable` with
9
+ the reason in `notes` and still exits `1`, so an empty `failures` array is
10
+ never mistaken for a pass. A local folder that happens to be named
11
+ `owner/repo` no longer hides the remote target. `test/audit-batch.test.mjs`,
12
+ `test/audit-rate-limit.test.mjs` and `test/remote.test.mjs` cover the
13
+ unreadable row, URL normalisation and the folder-name collision, and the
14
+ README's `--json` example is fenced as JSON so it renders as a code block.
15
+ - **`fix <owner>/<repo> --remote` exits `1` when there is nothing to apply.**
16
+ The command is a repair planner, so exit `0` now means it printed a unified
17
+ diff the author can apply. A manifest that already declares a valid
18
+ `engines.dsh` still prints `ok engines.dsh is already "<range>"; nothing to
19
+ apply` and writes no diff or patch file, but the plan is empty and the exit
20
+ code says so. This makes the remote repair usable in a shell loop that has to
21
+ tell a printed repair from an already-clean repository. The process-boundary
22
+ test now asserts both outcomes, and the README and `docs/repair.md` describe
23
+ the same contract.
24
+ - **`doctor --fix --host` aims the repaired `engines.dsh` at the DSH that
25
+ rejected the install.** The repair planner already accepted a host, but the
26
+ CLI never passed `--host` through, so `doctor --fix ./my-panel --host 0.3.0`
27
+ silently wrote the default `>=0.2.0` — the same range `fix --engines --host`
28
+ would have replaced. The flag now reaches the planner, the preview prints why
29
+ the next major is excluded, and `--write` applies exactly that range.
30
+ `test/doctor-fix.test.mjs` covers the host-aimed preview, the write and an
31
+ incomplete host version that must stop before reading the manifest.
32
+ - **A `package.json` that is not a JSON object is named instead of crashing.**
33
+ A file holding `null`, a string or an array parses as JSON, but every check
34
+ then read a field off the wrong shape: plain `doctor` died with
35
+ `Cannot read properties of null` and `doctor --fix` repeated that message.
36
+ The shared manifest reader now rejects the shape once with
37
+ `package.json does not hold a JSON object`, so the fixer reports the file the
38
+ same way it reports a parse error. The installed-plugin audit uses the same
39
+ reader and gets the cleaner message without a second code path.
40
+
1
41
  ## 0.20.33
2
42
 
3
43
  - **`fix --remote --patch` keeps a CRLF manifest's line endings in the diff.**
package/README.md CHANGED
@@ -600,6 +600,8 @@ For a CI job or a repair sweep, add `--json`:
600
600
  ```sh
601
601
  $ dsh-plugin audit --remote --from repos.txt --json
602
602
  ```
603
+
604
+ ```json
603
605
  [
604
606
  {
605
607
  "target": "V1ki/dsh-plugin-subscriptions",
@@ -746,6 +748,22 @@ and a range that already passes is not touched. `--range <range>` chooses the
746
748
  value used when `engines.dsh` needs repair, and `--dry-run` wins if it is passed
747
749
  alongside `--write`.
748
750
 
751
+ When the failed install names the host version, `--host` aims that repair at
752
+ the DSH that rejected it instead of falling back to the default. It is the same
753
+ decision as `fix --engines --host`, so the preview shows the range and why the
754
+ next major is excluded, and `--write` applies exactly that edit:
755
+
756
+ ```sh
757
+ $ npx dsh-plugin-toolkit@latest doctor --fix ./my-panel --host 0.3.0
758
+ dsh-plugin doctor --fix: 1 failed check(s) in /Users/you/my-panel
759
+ ✗ engines.dsh: package.json — would write engines.dsh ">=0.3.0 <1.0.0" (was missing)
760
+ host 0.3.0 is inside ">=0.3.0 <1.0.0"; 1.0.0 is excluded, so the range includes the host you run and stops before the next major
761
+ nothing written; pass --write to apply
762
+ ```
763
+
764
+ An incomplete version such as `--host 0.3` is refused before the manifest is
765
+ read, and `--range` still wins when both flags are passed.
766
+
749
767
  Checks that cannot be repaired without guessing — a missing patch file, a root
750
768
  export that points at the CLI, a README with no Requirements section — still
751
769
  appear in the plan with `manual:`, so the command never invents file contents.
@@ -838,8 +856,8 @@ dsh-plugin fix: would write engines.dsh ">=0.2.0" (was missing) in PrismLean/dsh
838
856
 
839
857
  When `package.json` already declares a range that clears the check, there is
840
858
  nothing to apply: the command prints `ok engines.dsh is already "<range>";
841
- nothing to apply` and exits `0`, the same no-op as `fix --engines` on a
842
- checkout. No diff and no patch file is written.
859
+ nothing to apply`, exits `1`, and writes no diff or patch file. Exit `0` means a
860
+ repair was printed for the author; `1` means there was no repair to print.
843
861
 
844
862
  To apply it, clone the repository, save that diff with `--patch`, and apply it
845
863
  in the checkout:
@@ -1073,8 +1091,8 @@ merged
1073
1091
 
1074
1092
  | Code | Meaning |
1075
1093
  | --- | --- |
1076
- | 0 | Done, or nothing to complain about — including `fix --remote` when `engines.dsh` is already a valid range |
1077
- | 1 | A check failed, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
1094
+ | 0 | Done, or nothing to complain about |
1095
+ | 1 | A check failed, a remote `fix` found nothing to apply, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
1078
1096
  | 2 | Unknown command, invalid usage, or a remote request that could not be completed |
1079
1097
 
1080
1098
  A flag that takes a value must be given one. When `--range`, `--log`,
@@ -1085,9 +1103,9 @@ is the last token, or is followed by another flag, the command exits `2` and
1085
1103
  names the flag instead of falling back to a default or consuming the next
1086
1104
  option as the value.
1087
1105
 
1088
- `fix <owner>/<repo> --remote` exits `0` both when it prints a diff for a missing
1089
- `engines.dsh` and when the manifest already declares a range that clears the
1090
- check; the second case prints `ok ... nothing to apply` and writes no diff.
1106
+ `fix <owner>/<repo> --remote` exits `0` when it prints a diff for a missing
1107
+ `engines.dsh`; when the manifest already declares a range that clears the check,
1108
+ the second case prints `ok ... nothing to apply`, writes no diff and exits `1`.
1091
1109
 
1092
1110
  ## What is not here yet
1093
1111
 
package/lib/audit.mjs CHANGED
@@ -21,7 +21,7 @@ import {
21
21
  } from './doctor.mjs';
22
22
  import { hostCompatibility } from './compat.mjs';
23
23
  import { readGraph } from './dev.mjs';
24
- import { auditRemote, fixRemote } from './remote.mjs';
24
+ import { auditRemote, fixRemote, parseTarget } from './remote.mjs';
25
25
  import { resolvePath } from './paths.mjs';
26
26
 
27
27
  export { hostCompatibility } from './compat.mjs';
@@ -395,6 +395,25 @@ export function patchFileName(target) {
395
395
  return `${parts[1]}__${parts[2]}.patch`;
396
396
  }
397
397
 
398
+ /**
399
+ * The name a finding reports for a target. A readable row carries the parsed
400
+ * slug already, but a row that was skipped after a rate limit or refused before
401
+ * the read has only the input string. Normalise that string through the same
402
+ * parser the read would use, so a list of GitHub URLs produces `owner/repo` for
403
+ * every row and a consumer can join the findings without rewriting targets.
404
+ * An invalid entry keeps the text the caller wrote; the failure row for it
405
+ * already says what was wrong.
406
+ */
407
+ function targetName(value) {
408
+ if (value !== null && typeof value === 'object' && typeof value.slug === 'string') return value.slug;
409
+ if (typeof value !== 'string') return String(value ?? '');
410
+ try {
411
+ return parseTarget(value).slug;
412
+ } catch {
413
+ return value;
414
+ }
415
+ }
416
+
398
417
  function noteMessages(report) {
399
418
  if (Array.isArray(report?.notes)) return report.notes;
400
419
  const messages = report?.notes?.messages;
@@ -412,7 +431,7 @@ function noteMessages(report) {
412
431
  export function remoteFinding(report, host) {
413
432
  const manifest = report?.manifest ?? null;
414
433
  const finding = {
415
- target: report?.target?.slug ?? String(report?.target ?? ''),
434
+ target: targetName(report?.target),
416
435
  version: manifest === null ? null : manifestVersion(manifest),
417
436
  hostRange: manifest === null ? null : hostRange(manifest),
418
437
  failures: (report?.failures ?? []).map((failure) => ({
@@ -546,7 +565,7 @@ export async function auditRemoteTargets(
546
565
  const skipped = (target) => {
547
566
  const reset = rateLimitState.info?.resetAt;
548
567
  const row = {
549
- target: String(target),
568
+ target: targetName(target),
550
569
  version: null,
551
570
  hostRange: null,
552
571
  failures: [],
@@ -593,7 +612,7 @@ export async function auditRemoteTargets(
593
612
  } catch (error) {
594
613
  row = withHostCompatibility(
595
614
  {
596
- target: String(target),
615
+ target: targetName(target),
597
616
  version: null,
598
617
  hostRange: null,
599
618
  failures: [{ check: 'target', message: error instanceof Error ? error.message : String(error) }],
package/lib/cli.mjs CHANGED
@@ -30,6 +30,7 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
30
30
 
31
31
  dsh-plugin doctor --fix [dir] print the repair plan; write it only with --write
32
32
  dsh-plugin doctor --fix ./my-panel --write
33
+ dsh-plugin doctor --fix ./my-panel --host 0.3.0 aim the range at the DSH that rejected it
33
34
 
34
35
  dsh-plugin fix <dir> --engines print the host range doctor asks for; write it only with --write
35
36
  dsh-plugin fix ./my-panel --engines --write
@@ -100,7 +101,7 @@ Flags
100
101
  --from <file> with audit --remote: read owner/repo entries from <file>, one per line; - means standard input
101
102
  --jobs <n> with audit --remote: read n repositories at once, default 4, capped at 8
102
103
  --patch-dir <dir> with audit --remote: write one .patch per repository that needs a repair
103
- --host <value> with audit: the running app URL; with audit --remote or fix: the complete DSH version to compare against or aim at
104
+ --host <value> with audit: the running app URL; with audit --remote or fix (including doctor --fix): the complete DSH version to compare against or aim at
104
105
  --json with audit --remote: print the findings as JSON, one object per repository
105
106
  --index <path> index file, default market/index.json
106
107
  --market <dir> with release: a checkout of the repository that holds the index
@@ -420,6 +421,10 @@ export async function run(argv, io = console, deps = {}) {
420
421
  result = doctorFix({
421
422
  dir,
422
423
  range: options.range,
424
+ // The failed install usually names the DSH version; aiming the repair
425
+ // at it is the same decision `fix --engines --host` makes, so one range
426
+ // is written whichever repair command the author reaches for.
427
+ host: options.host,
423
428
  // A dry run is the default, and --dry-run wins if somebody passes both.
424
429
  write: options.write === true,
425
430
  dryRun: options.dryRun === true,
@@ -448,6 +453,10 @@ export async function run(argv, io = console, deps = {}) {
448
453
  io.log(` ✗ ${entry.check}: ${entry.path} — manual: ${entry.manual}`);
449
454
  }
450
455
  }
456
+ // A range aimed at a named host is a decision, not just a string: show the
457
+ // sentence `fix --engines --host` already prints so the author can see why
458
+ // the next major is excluded.
459
+ if (typeof result.why === 'string' && result.why.length > 0) io.log(` ${result.why}`);
451
460
 
452
461
  if (result.written === true) {
453
462
  for (const entry of result.edits) {
@@ -515,12 +524,14 @@ export async function run(argv, io = console, deps = {}) {
515
524
  return 2;
516
525
  }
517
526
  if (result.changed !== true) {
518
- // A manifest that already declares a range clearing the check is a
519
- // successful repair plan, exactly like the local `fix --engines` no-op:
520
- // there is no failure to report, so the documented exit code is 0.
527
+ // This command exists to produce a repair, so "nothing to apply" is not
528
+ // success: no diff was printed and no patch file was written. Exit 1
529
+ // lets a loop over the ecosystem tell a repair that was handed to the
530
+ // author (0) from a repository that already passes (1) without parsing
531
+ // stdout. The message still names the range, so the reason is visible.
521
532
  io.log(`ok engines.dsh is already "${result.range}"; nothing to apply`);
522
533
  if (typeof result.why === 'string' && result.why.length > 0) io.log(` ${result.why}`);
523
- return 0;
534
+ return 1;
524
535
  }
525
536
  const was = result.before === null ? 'missing' : `"${result.before}"`;
526
537
  io.log(`dsh-plugin fix: would write engines.dsh "${result.range}" (was ${was}) in ${result.target.slug}`);
package/lib/doctor.mjs CHANGED
@@ -93,6 +93,14 @@ export function readManifestSource(dir) {
93
93
  } catch (error) {
94
94
  throw new Error(`${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
95
95
  }
96
+ // npm's manifest is an object. A file holding `null`, a string or an array
97
+ // parses as JSON but every check would then read a field off the wrong shape;
98
+ // `doctor` used to fail with a bare `Cannot read properties of null` instead
99
+ // of naming the file. Reject it once here so `doctor`, `doctor --fix` and the
100
+ // installed-plugin audit all report the same actionable sentence.
101
+ if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest) === true) {
102
+ throw new Error(`${manifestPath} does not hold a JSON object`);
103
+ }
96
104
  return { manifest, manifestPath, raw, target };
97
105
  }
98
106
 
package/lib/remote.mjs CHANGED
@@ -146,12 +146,23 @@ export function tokenOf(env = process.env) {
146
146
  * drift.
147
147
  */
148
148
  export function parseTarget(target) {
149
+ const raw = typeof target === 'string' ? target.trim() : '';
149
150
  const parsed = classifyTarget(target);
150
151
  if (parsed.kind === 'repo') {
151
152
  const { owner, repo } = parsed;
152
153
  return { owner, repo, slug: `${owner}/${repo}` };
153
154
  }
154
155
  if (parsed.kind === 'local') {
156
+ // `classifyTarget` answers "local" for an `owner/repo` string when a folder
157
+ // of that name happens to exist. These commands were told the target is
158
+ // remote, so the syntactic slug wins over the local tree; only a path that
159
+ // cannot be a slug is still refused.
160
+ const slug = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/u.exec(raw);
161
+ if (slug !== null) {
162
+ const owner = slug[1];
163
+ const repo = slug[2].replace(/\.git$/iu, '');
164
+ return { owner, repo, slug: `${owner}/${repo}` };
165
+ }
155
166
  throw new Error(`${JSON.stringify(target)} is a folder on this machine; run \`dsh-plugin doctor ${target}\` instead`);
156
167
  }
157
168
  if (parsed.kind === 'search') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.33",
3
+ "version": "0.20.34",
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": {