dsh-plugin-toolkit 0.20.43 → 0.20.45

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,34 @@
1
+ ## 0.20.45
2
+
3
+ - **The reproducible compatibility sample answers for the DSH version the
4
+ reader runs, not only the canary in the reports.**
5
+ `node scripts/compatibility-sample.mjs --host 0.1.5` replays the frozen
6
+ `L3n3L/dsh-resume@0.1.3` manifest through the shipped CLI and prints the
7
+ `compatible` line the README now shows; the default command still prints and
8
+ checks the documented `incompatible` line. With an explicit `--host` the
9
+ wrapper exits with the replayed command's status, so a CI step can gate on
10
+ `0`/`1`, while an invalid version reaches the CLI's own complete-version
11
+ refusal and exits `2` instead of printing a misleading row.
12
+ `test/readme-compatibility.test.mjs` compares both documented blocks with the
13
+ sample, pins the forwarded statuses, and now invokes the parser with every
14
+ documented compatibility flag so a README flag cannot survive only in the
15
+ help text.
16
+
17
+ ## 0.20.44
18
+
19
+ - **`audit --home` reports a declared bundle whose `package.json` parses but has
20
+ no `dsh` field.** The install scan skipped every package without a `dsh` field
21
+ as an ordinary dependency, even when the profile named it in
22
+ `dsh.profile.bundles`. A profile that mounted one such broken bundle printed
23
+ "no plugins installed in any profile" and exited 0, so CI saw a clean profile
24
+ the loader could not mount. The scan now emits a `no dsh field` row with a
25
+ `dsh field` failure naming the declaring `package.json` and exits 1. Packages
26
+ the profile does not declare keep the old skip, so a profile containing only
27
+ ordinary dependencies still exits 0. `test/audit-home-no-dsh.test.mjs` pins
28
+ the ghost row and its exit status at the CLI beside a valid declared bundle
29
+ and a profile holding only ordinary dependencies, while `test/audit.test.mjs`
30
+ covers the row and the declared-name fallback.
31
+
1
32
  ## 0.20.43
2
33
 
3
34
  - **A host-aimed repair keeps the floor of a hyphen range that crosses the next
package/README.md CHANGED
@@ -327,8 +327,9 @@ directory still exits `0` with that line, and omitting `--home` still scans the
327
327
  default `~/.dsh`.
328
328
 
329
329
  Without `--host` the loaded column is `?`, because guessing would be worse than
330
- saying nothing. Only packages that declare a `dsh` field are audited — the rest of
331
- `node_modules` is ordinary dependencies, and auditing those is noise.
330
+ saying nothing. Only packages that declare a `dsh` field, plus packages the
331
+ profile names in `dsh.profile.bundles`, are audited — the rest of `node_modules`
332
+ is ordinary dependencies, and auditing those is noise.
332
333
 
333
334
  An installed package whose `package.json` cannot be read is the exception: the
334
335
  `dsh` field that would mark it as a plugin is in the file that failed to parse.
@@ -341,6 +342,13 @@ damaged `package.json` in a package that is neither in `dsh.profile.bundles` nor
341
342
  readable enough to expose a `dsh` field is still an ordinary dependency and is
342
343
  skipped, so one broken transitive install does not fail every audit.
343
344
 
345
+ A declared bundle can also parse but carry no `dsh` field at all. The profile
346
+ says the loader will mount it, so `audit` prints a `no dsh field` row with a
347
+ `dsh field` failure naming the declaring `package.json` and exits `1`, instead
348
+ of skipping the package and reporting the profile as having no plugins. The
349
+ skip still applies to a package that is not in `dsh.profile.bundles`; a profile
350
+ containing only ordinary dependencies prints no plugin rows and exits `0`.
351
+
344
352
  A declared bundle can also be missing entirely. If a name stays in
345
353
  `dsh.profile.bundles` after its `node_modules/<name>` folder is removed (an
346
354
  interrupted install, or a package deleted by hand), `audit` prints a `missing`
@@ -491,9 +499,31 @@ incompatible L3n3L/dsh-resume 0.1.3 (host >=0.1.0-rc.6 <0.2.0-0) [incompatible
491
499
  summary: 1 repository — 0 clean, 1 failing (1 problem), 0 unreadable, 0 rate-limited
492
500
  ```
493
501
 
494
- The verdict comes first: `incompatible` means the range in `package.json` does
502
+ The sample defaults to that canary. Pass `--host` to ask the same frozen 0.1.3
503
+ manifest about the version you actually run; this is the same range against an
504
+ older stable host it accepts:
505
+
506
+ ```sh
507
+ $ node scripts/compatibility-sample.mjs --host 0.1.5
508
+ clean L3n3L/dsh-resume 0.1.3 (host >=0.1.0-rc.6 <0.2.0-0) [compatible with dsh 0.1.5; declares ">=0.1.0-rc.6 <0.2.0-0"]
509
+
510
+ summary: 1 repository — 1 clean, 0 failing (0 problems), 0 unreadable, 0 rate-limited
511
+ ```
512
+
513
+ With an explicit `--host` the wrapper exits with the replayed command's status
514
+ (`0` for this compatible line, `1` for a version the range rejects), so it can
515
+ gate a CI step. The default form still exits `0` only after the documented
516
+ incompatible replay exited `1`. An invalid version such as `banana` reaches the
517
+ CLI's own `--host needs a complete DSH version` refusal and exits `2` instead
518
+ of printing a clean-looking row.
519
+
520
+ The line starts with the repository verdict: `clean` when the range accepts the
521
+ host and every check passes, `incompatible` when the range is the failing fact.
522
+ The bracketed `compatibility` field is the direct answer. `incompatible` means
523
+ the range in `package.json` does
495
524
  not accept the host, so the installer rejects the plugin before it unpacks it.
496
- This run exits `1`. The same answer is reproducible without a GitHub request:
525
+ An incompatible run exits `1`. The same answer is reproducible without a GitHub
526
+ request:
497
527
  the checked-in snapshot under `examples/compatibility-sample/` keeps the 0.1.3
498
528
  manifest fields that decide compatibility, and its `## Requirements` heading
499
529
  isolates the host-range answer. This command feeds that snapshot through the
@@ -17,3 +17,9 @@ The heading is here on purpose: the sample isolates the host-range verdict, and
17
17
  the remote audit still checks README requirements. Upstream's localized README
18
18
  does not use a `## Requirements` heading, so a live audit of the repository can
19
19
  also add a `readme` failure to the same row.
20
+
21
+ `node scripts/compatibility-sample.mjs` compares this manifest with the
22
+ `0.2.2-alpha.3` canary from the reports. Add `--host <version>` to ask the same
23
+ frozen manifest about the DSH version you run; the wrapper then exits with the
24
+ replayed CLI's status, so `--host 0.1.5` exits `0` and a range-excluding version
25
+ exits `1`.
package/lib/audit.mjs CHANGED
@@ -12,6 +12,7 @@ import os from 'node:os';
12
12
  import path from 'node:path';
13
13
 
14
14
  import {
15
+ checkDshField,
15
16
  checkHostCompatibility,
16
17
  doctor,
17
18
  hostRange,
@@ -138,6 +139,26 @@ function missingInstalled({ dir, name, profile }) {
138
139
  };
139
140
  }
140
141
 
142
+ /**
143
+ * A declared bundle whose `package.json` parses but has no `dsh` field. The
144
+ * folder is installed and `dsh.profile.bundles` names it, so the loader will
145
+ * look for a plugin definition that is not there. Skipping it as an ordinary
146
+ * dependency made a profile with one broken declared bundle report "no plugins
147
+ * installed" and exit 0, which is the false clean this record prevents.
148
+ */
149
+ function noDshInstalled({ dir, name, manifest, profile, manifestPath }) {
150
+ return {
151
+ dir,
152
+ // The profile's list is the name the loader will look for, so the row names
153
+ // the declared bundle even if its manifest omits `name` (or disagrees).
154
+ manifest: { ...manifest, name },
155
+ profile,
156
+ manifestPath,
157
+ noDsh: true,
158
+ error: checkDshField(manifest),
159
+ };
160
+ }
161
+
141
162
  /** Every package folder inside every profile, scoped names included. */
142
163
  export function listInstalled({ home = DEFAULT_HOME } = {}) {
143
164
  const root = resolvePath(home);
@@ -221,8 +242,16 @@ export function listInstalled({ home = DEFAULT_HOME } = {}) {
221
242
  continue;
222
243
  }
223
244
  // Only packages that declare themselves as plugins. node_modules is full
224
- // of ordinary dependencies, and auditing those is noise.
225
- if (manifest.dsh === undefined) continue;
245
+ // of ordinary dependencies, and auditing those is noise. A package the
246
+ // profile lists in `dsh.profile.bundles` is different: the profile says
247
+ // the loader will mount it, so a parsed manifest without a dsh field is
248
+ // a broken declared bundle, not an ordinary dependency to omit.
249
+ if (manifest.dsh === undefined) {
250
+ if (listedInProfile === true) {
251
+ found.push(noDshInstalled({ dir, name, manifest, profile, manifestPath }));
252
+ }
253
+ continue;
254
+ }
226
255
  found.push({ dir, manifest, profile });
227
256
  }
228
257
  }
@@ -823,60 +852,71 @@ export async function audit({
823
852
  }
824
853
 
825
854
  const profileFiles = new Map();
826
- const rows = installed.map(({ dir, manifest, profile, manifestPath, unreadable = false, missing = false, error }) => {
827
- let failures;
828
- if (missing === true) {
829
- // The folder is gone, so there is no manifest for doctor to read. The
830
- // profile record is the evidence, and the row must name the absent path.
831
- failures = [{ check: 'install', message: error }];
832
- } else if (unreadable === true) {
833
- // doctor would throw on the same file; keep the read error the install
834
- // scan already recorded so the row names the unreadable package.json.
835
- failures = [{ check: 'manifest', message: error }];
836
- } else {
837
- try {
838
- ({ failures } = doctor(dir, { installed: true }));
839
- } catch (caught) {
840
- failures = [{ check: 'manifest', message: caught.message }];
855
+ const rows = installed.map(
856
+ ({ dir, manifest, profile, manifestPath, unreadable = false, missing = false, noDsh = false, error }) => {
857
+ let failures;
858
+ if (missing === true) {
859
+ // The folder is gone, so there is no manifest for doctor to read. The
860
+ // profile record is the evidence, and the row must name the absent path.
861
+ failures = [{ check: 'install', message: error }];
862
+ } else if (unreadable === true) {
863
+ // doctor would throw on the same file; keep the read error the install
864
+ // scan already recorded so the row names the unreadable package.json.
865
+ failures = [{ check: 'manifest', message: error }];
866
+ } else if (noDsh === true) {
867
+ // The declared bundle's manifest parses, but there is no `dsh` field for
868
+ // the loader to mount. Say that once, in the same check name doctor uses.
869
+ failures = [{ check: 'dsh field', message: error ?? checkDshField(manifest) }];
870
+ } else {
871
+ try {
872
+ ({ failures } = doctor(dir, { installed: true }));
873
+ } catch (caught) {
874
+ failures = [{ check: 'manifest', message: caught.message }];
875
+ }
841
876
  }
842
- }
843
- const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
844
- let explanation = null;
845
- if (missing === true) {
846
- explanation = {
847
- reason: `dsh.profile.bundles lists it, but ${dir} is missing, so there is no installed copy to mount`,
848
- action: `reinstall ${manifest.name} (for example \`dsh plugin add ${manifest.name}\`), then restart the app`,
849
- };
850
- } else if (unreadable === true) {
851
- explanation = {
852
- reason: `${manifestPath} is unreadable, so the loader cannot tell what to mount`,
853
- action: `reinstall ${manifest.name} so its package.json is written completely`,
854
- };
855
- } else if (loaded === false) {
856
- if (profileFiles.has(profile) === false) {
857
- profileFiles.set(profile, readProfileBundles({ home, profile }));
877
+ const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
878
+ let explanation = null;
879
+ if (missing === true) {
880
+ explanation = {
881
+ reason: `dsh.profile.bundles lists it, but ${dir} is missing, so there is no installed copy to mount`,
882
+ action: `reinstall ${manifest.name} (for example \`dsh plugin add ${manifest.name}\`), then restart the app`,
883
+ };
884
+ } else if (unreadable === true) {
885
+ explanation = {
886
+ reason: `${manifestPath} is unreadable, so the loader cannot tell what to mount`,
887
+ action: `reinstall ${manifest.name} so its package.json is written completely`,
888
+ };
889
+ } else if (noDsh === true) {
890
+ explanation = {
891
+ reason: 'dsh.profile.bundles lists it, but its package.json parses with no "dsh" field, so the loader has nothing to mount',
892
+ action: `add dsh.bundle.patch to ${manifestPath} (and ship the patch file it names), or remove "${manifest.name}" from dsh.profile.bundles, then restart the app`,
893
+ };
894
+ } else if (loaded === false) {
895
+ if (profileFiles.has(profile) === false) {
896
+ profileFiles.set(profile, readProfileBundles({ home, profile }));
897
+ }
898
+ const listed = profileFiles.get(profile);
899
+ explanation = explainNotLoaded({
900
+ manifest,
901
+ name: manifest.name,
902
+ profileFile: listed.file,
903
+ bundles: listed.bundles,
904
+ });
858
905
  }
859
- const listed = profileFiles.get(profile);
860
- explanation = explainNotLoaded({
861
- manifest,
906
+ return {
862
907
  name: manifest.name,
863
- profileFile: listed.file,
864
- bundles: listed.bundles,
865
- });
866
- }
867
- return {
868
- name: manifest.name,
869
- version: manifest.version ?? '?',
870
- profile,
871
- dir,
872
- failures,
873
- ...split(failures),
874
- loaded,
875
- unreadable: unreadable === true,
876
- missing: missing === true,
877
- reason: explanation?.reason ?? null,
878
- action: explanation?.action ?? null,
879
- };
908
+ version: manifest.version ?? '?',
909
+ profile,
910
+ dir,
911
+ failures,
912
+ ...split(failures),
913
+ loaded,
914
+ unreadable: unreadable === true,
915
+ missing: missing === true,
916
+ noDsh: noDsh === true,
917
+ reason: explanation?.reason ?? null,
918
+ action: explanation?.action ?? null,
919
+ };
880
920
  });
881
921
 
882
922
  const width = Math.max(...rows.map((row) => row.name.length), 6);
@@ -887,15 +927,20 @@ export async function audit({
887
927
  ? 'missing'
888
928
  : row.unreadable === true
889
929
  ? 'unreadable'
890
- : row.loaded === null
891
- ? '?'
892
- : row.loaded === true
893
- ? 'loaded'
894
- : 'not loaded';
895
- const reason = row.missing === true || row.loaded === false || row.unreadable === true ? ` — ${row.reason}` : '';
930
+ : row.noDsh === true
931
+ ? 'no dsh field'
932
+ : row.loaded === null
933
+ ? '?'
934
+ : row.loaded === true
935
+ ? 'loaded'
936
+ : 'not loaded';
937
+ const reason =
938
+ row.missing === true || row.noDsh === true || row.loaded === false || row.unreadable === true
939
+ ? ` — ${row.reason}`
940
+ : '';
896
941
  io.log(`${row.name.padEnd(width)} ${String(row.version).padEnd(8)} ${state.padEnd(10)} ${describe(row)}${reason}`);
897
942
  for (const failure of row.failures) io.log(`${' '.repeat(width + 22)}${failure.check}: ${failure.message}`);
898
- if (row.missing === true || row.loaded === false || row.unreadable === true) {
943
+ if (row.missing === true || row.noDsh === true || row.loaded === false || row.unreadable === true) {
899
944
  io.log(`${detailIndent}fix: ${row.action}`);
900
945
  }
901
946
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.43",
3
+ "version": "0.20.45",
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": {
@@ -12,9 +12,16 @@
12
12
  *
13
13
  * Run: node scripts/compatibility-sample.mjs
14
14
  * node scripts/compatibility-sample.mjs --json
15
+ * node scripts/compatibility-sample.mjs --host 0.1.5
15
16
  *
16
17
  * `--json` replays the same command with the flag CI reads, so the machine
17
18
  * form is checked against the executable too, not just described in prose.
19
+ * `--host` asks the same frozen manifest about another DSH version, so a
20
+ * reader can reproduce the answer for the host they actually run; the default
21
+ * stays the canary from the reports. With an explicit host the script passes
22
+ * the replayed command's exit status through, because that is the status a CI
23
+ * step would gate on. Without it the wrapper exits 0 only after the known
24
+ * incompatible replay exited 1.
18
25
  */
19
26
  import { spawnSync } from 'node:child_process';
20
27
  import fs from 'node:fs';
@@ -27,15 +34,39 @@ const ROOT = path.join(HERE, '..');
27
34
  const SAMPLE = path.join(ROOT, 'examples', 'compatibility-sample');
28
35
  const BIN = path.join(ROOT, 'bin', 'dsh-plugin.mjs');
29
36
  const TARGET = 'L3n3L/dsh-resume';
30
- const HOST = '0.2.2-alpha.3';
31
- const JSON_OUTPUT = process.argv.includes('--json');
37
+ const DEFAULT_HOST = '0.2.2-alpha.3';
32
38
 
33
- const unknown = process.argv.slice(2).filter((argument) => argument !== '--json');
34
- if (unknown.length > 0) {
35
- process.stderr.write(`compatibility-sample: unknown argument ${unknown.join(' ')}; use --json for the machine form\n`);
39
+ function usage(message) {
40
+ process.stderr.write(`compatibility-sample: ${message}\n`);
36
41
  process.exit(2);
37
42
  }
38
43
 
44
+ let JSON_OUTPUT = false;
45
+ let HOST = DEFAULT_HOST;
46
+ let HOST_EXPLICIT = false;
47
+ const args = process.argv.slice(2);
48
+ for (let index = 0; index < args.length; index += 1) {
49
+ const argument = args[index];
50
+ if (argument === '--json') {
51
+ JSON_OUTPUT = true;
52
+ } else if (argument === '--host') {
53
+ const value = args[index + 1];
54
+ if (value === undefined || value.startsWith('--') === true) {
55
+ usage('--host needs a complete DSH version, for example --host 0.2.2');
56
+ }
57
+ HOST = value;
58
+ HOST_EXPLICIT = true;
59
+ index += 1;
60
+ } else if (argument.startsWith('--host=') === true) {
61
+ const value = argument.slice('--host='.length);
62
+ if (value.trim() === '') usage('--host needs a complete DSH version, for example --host 0.2.2');
63
+ HOST = value;
64
+ HOST_EXPLICIT = true;
65
+ } else {
66
+ usage(`unknown argument ${argument}; use --json or --host <version>`);
67
+ }
68
+ }
69
+
39
70
  // A CommonJS preload works on every Node version the package supports; an
40
71
  // `--import` hook would require a newer Node than `engines` promises.
41
72
  const PRELOAD = `
@@ -87,18 +118,39 @@ function replay() {
87
118
  });
88
119
  if (result.error !== undefined) throw result.error;
89
120
  const stderr = String(result.stderr ?? '').trim();
90
- if (result.status !== 1) {
91
- throw new Error(
92
- `the compatibility sample answered ${result.status ?? 'no status'}; the documented incompatible answer exits 1${
93
- stderr === '' ? '' : `\n${stderr}`
94
- }`,
95
- );
121
+ // The CLI validates `--host` at the same boundary a real run uses. Forward
122
+ // that usage refusal instead of turning it into a wrapper stack trace; a
123
+ // typo in the version must not look like a successful replay.
124
+ if (result.status === 2) {
125
+ if (stderr === '') throw new Error('the compatibility sample exited 2 without saying why');
126
+ return { stdout: String(result.stdout ?? ''), stderr, status: 2 };
127
+ }
128
+ if (HOST_EXPLICIT === false) {
129
+ if (result.status !== 1) {
130
+ throw new Error(
131
+ `the compatibility sample answered ${result.status ?? 'no status'}; the documented incompatible answer exits 1${
132
+ stderr === '' ? '' : `\n${stderr}`
133
+ }`,
134
+ );
135
+ }
136
+ if (stderr !== '') throw new Error(`the compatibility sample wrote to stderr:\n${stderr}`);
137
+ // The wrapper's own 0 means the documented incompatible answer was
138
+ // reproduced; the default command is a demonstration, not a gate.
139
+ return { stdout: String(result.stdout ?? ''), stderr: '', status: 0 };
140
+ }
141
+ if (result.status !== 0 && result.status !== 1) {
142
+ throw new Error(`the compatibility sample answered ${result.status ?? 'no status'}${stderr === '' ? '' : `\n${stderr}`}`);
96
143
  }
97
144
  if (stderr !== '') throw new Error(`the compatibility sample wrote to stderr:\n${stderr}`);
98
- return result.stdout;
145
+ // An explicit host is a question whose answer a reader may gate on, so the
146
+ // wrapper exits with the replayed CLI's status.
147
+ return { stdout: String(result.stdout ?? ''), stderr: '', status: result.status };
99
148
  } finally {
100
149
  fs.rmSync(scratch, { recursive: true, force: true });
101
150
  }
102
151
  }
103
152
 
104
- process.stdout.write(replay());
153
+ const replayed = replay();
154
+ if (replayed.stdout !== '') process.stdout.write(replayed.stdout);
155
+ if (replayed.stderr !== '') process.stderr.write(`${replayed.stderr}\n`);
156
+ process.exitCode = replayed.status;