dsh-plugin-toolkit 0.20.15 → 0.20.17

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,39 @@
1
+ ## 0.20.17
2
+
3
+ - **`audit` reports a declared bundle whose folder is gone.** When a package
4
+ name stayed in `dsh.profile.bundles` but its `node_modules/<name>` folder had
5
+ been removed, the install scan never saw the package and `audit --home`
6
+ printed only its healthy siblings, so the command exited `0` and hid the
7
+ reason the loader could not mount it. The scan now starts from the profile's
8
+ declared bundles and prints a `missing` row with an `install` failure naming
9
+ the absent `node_modules/<name>` path; the valid siblings are still listed
10
+ and the command exits `1`. A package that is absent but undeclared is still
11
+ ignored, so ordinary dependencies do not appear. A regression test pins the
12
+ module result and the spawned CLI exit code in both directions: the declared
13
+ missing bundle exits `1`, and the same home with the name removed from the
14
+ profile exits `0` without printing it. A checked-in home at
15
+ `test/fixtures/missing-declared-bundle` also keeps the minimal case — one
16
+ declared name and no `node_modules` directory at all — reproducible through
17
+ `audit --home`, so the scan cannot fall back to "nothing installed" and exit
18
+ clean again.
19
+
20
+ ## 0.20.16
21
+
22
+ - **`doctor` names a root export that cannot be loaded.** A package whose
23
+ `exports["."]` (or `main`) named a missing file printed `ok` and exited `0`,
24
+ while the same package would fail when the loader imported it; a target that
25
+ was a directory crashed `doctor` with a raw `EISDIR` from `readFileSync`. The
26
+ `root export` check now asks the filesystem what the resolved path is and
27
+ reports a missing file, a directory, or an unreadable file as a named failure
28
+ before reading source. `verify --no-mount` stops at that same `doctor` check
29
+ instead of reaching pack or install. Four fixtures pin the behavior through
30
+ the shipped CLI: a string root, an `exports["."]` string and a conditions
31
+ object naming `missing.js`, and an export naming the `lib` directory all exit
32
+ `1` with a `root export:` line naming the target and no raw `EISDIR`, and
33
+ `verify --no-mount` on the same fixtures exits `1` at `stopped at doctor`
34
+ without a `pack:` failure, while the unmodified `init` scaffold still passes
35
+ both commands.
36
+
1
37
  ## 0.20.15
2
38
 
3
39
  - **A strict comparison against a wildcard major matches nothing.** `audit
package/README.md CHANGED
@@ -324,6 +324,15 @@ damaged `package.json` in a package that is neither in `dsh.profile.bundles` nor
324
324
  readable enough to expose a `dsh` field is still an ordinary dependency and is
325
325
  skipped, so one broken transitive install does not fail every audit.
326
326
 
327
+ A declared bundle can also be missing entirely. If a name stays in
328
+ `dsh.profile.bundles` after its `node_modules/<name>` folder is removed (an
329
+ interrupted install, or a package deleted by hand), `audit` prints a `missing`
330
+ row with an `install` failure naming the absent folder and exits `1`, while
331
+ still listing the healthy plugins on the same run. An absent package that the
332
+ profile never declared is not an install record, so it is not invented in the
333
+ report; a regression test removes the name from the profile and requires the
334
+ shipped CLI to exit `0` without printing it.
335
+
327
336
  ## Edit a plugin that is already installed
328
337
 
329
338
  The host already swaps a rebuilt bundle without a page reload: it watches each plugin's entry artifact and reports a `rebuilt` frame on `/plugins/events`. `dev` puts the new file where the host is looking, then **proves** the frame arrived instead of asking you to check by eye.
@@ -683,9 +692,9 @@ the diff in the terminal.
683
692
  | `patch file` | The path declared above must be a real file |
684
693
  | `client entry` | If `dsh.client` is declared, the bundle has to be there |
685
694
  | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` |
686
- | `root export` | The loader imports the bare package name; if that module is the CLI (or exports no `apply`), the row mounts nothing while the install reports success |
695
+ | `root export` | The loader imports the bare package name; if that module is missing, is a directory, is the CLI, or exports no `apply`, the row mounts nothing while the install reports success |
687
696
 
688
- The `root export` check is a source check, not an install. `doctor` resolves the module the loader imports — `exports["."]` when it is a string or a conditions object (`default`, `import`, `require`, `node`, `module-sync`), otherwise `main` — then removes comments and the contents of string, template and regex literals before looking for a real export. It accepts `export function apply`, `export async function apply`, `export const apply = ...` (also `let` and `var`), `export { apply }` (including `export { helper as apply }`), `exports.apply = ...`, and an `apply` property in `module.exports = { ... }`. A comment such as `// TODO: export function apply() {}` is not an export, and `doctor` never imports or runs the plugin to decide. `verify --no-mount` installs the tarball and imports that same module, so it reaches the same verdict; `npm test` spawns the shipped CLI on the comment-only fixture and requires both commands to exit `1`.
697
+ The `root export` check is a source check, not an install. `doctor` resolves the module the loader imports — `exports["."]` when it is a string or a conditions object (`default`, `import`, `require`, `node`, `module-sync`), otherwise `main` — then checks that the path is a readable regular file, removes comments and the contents of string, template and regex literals, and looks for a real export. A missing file, a directory and an unreadable file are reported as `root export` failures naming the target instead of being skipped or raising a raw `EISDIR`; on a directory the install would have failed at import too. It accepts `export function apply`, `export async function apply`, `export const apply = ...` (also `let` and `var`), `export { apply }` (including `export { helper as apply }`), `exports.apply = ...`, and an `apply` property in `module.exports = { ... }`. A comment such as `// TODO: export function apply() {}` is not an export, and `doctor` never imports or runs the plugin to decide. `verify --no-mount` runs `doctor` first, so it stops at that same check instead of packing a package whose root cannot load; `npm test` spawns the shipped CLI for both commands on the comment-only fixtures and the missing-file, missing-conditions-file, string-root missing-file and directory fixtures, requires every one to exit `1` with a `root export:` line and no raw `EISDIR`, and requires `verify` to report `stopped at doctor` rather than a `pack:` failure. The unmodified scaffold still passes both commands.
689
698
 
690
699
  Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged. `doctor --remote` and `audit --remote` run the same manifest and README checks (`name`, `version`, `engines.dsh`, `dsh field`, `files list`, `readme`) against the `package.json` and README GitHub serves, then check the files the manifest points at, so a bad package name or a README with no Requirements heading is reported before a clone or install. The `name` check is pinned at the process boundary: `npm test` expects the shipped CLI to reject a missing, empty and malformed name (`accepted=0/3`) and to accept a valid plain or scoped control.
691
700
 
package/lib/audit.mjs CHANGED
@@ -111,6 +111,22 @@ function unreadableInstalled({ dir, name, profile, manifestPath, message }) {
111
111
  };
112
112
  }
113
113
 
114
+ /**
115
+ * A name in `dsh.profile.bundles` with no folder to mount. Unlike an ordinary
116
+ * dependency, this one is a declared plugin: the loader will look for it on
117
+ * startup, so a missing install has to appear in the audit instead of vanishing
118
+ * with the folder.
119
+ */
120
+ function missingInstalled({ dir, name, profile }) {
121
+ return {
122
+ dir,
123
+ manifest: { name },
124
+ profile,
125
+ missing: true,
126
+ error: `${dir} is missing, so dsh.profile.bundles lists "${name}" but there is no node_modules/${name} folder to mount`,
127
+ };
128
+ }
129
+
114
130
  /** Every package folder inside every profile, scoped names included. */
115
131
  export function listInstalled({ home = DEFAULT_HOME } = {}) {
116
132
  const root = resolvePath(home);
@@ -119,81 +135,99 @@ export function listInstalled({ home = DEFAULT_HOME } = {}) {
119
135
  const found = [];
120
136
  for (const profile of fs.readdirSync(profiles).sort()) {
121
137
  const modules = path.join(profiles, profile, 'node_modules');
122
- if (fs.existsSync(modules) === false) continue;
123
- const declared = new Set(readProfileBundles({ home, profile }).bundles);
124
- for (const entry of fs.readdirSync(modules).sort()) {
125
- if (entry.startsWith('.') === true) continue;
126
- const candidates = entry.startsWith('@')
127
- ? fs
128
- .readdirSync(path.join(modules, entry))
129
- .sort()
130
- .map((name) => ({ dir: path.join(modules, entry, name), name: `${entry}/${name}` }))
131
- : [{ dir: path.join(modules, entry), name: entry }];
132
- for (const { dir, name } of candidates) {
133
- // A broken package.json is only evidence of a plugin when the profile
134
- // says it mounts that name. Without that record an ordinary dependency
135
- // whose install was interrupted must stay out of the audit, or one bad
136
- // transitive package would turn every profile red.
137
- const listedInProfile = declared.has(name) === true;
138
- const manifestPath = path.join(dir, 'package.json');
139
- if (fs.existsSync(manifestPath) === false) {
140
- if (listedInProfile === true) {
141
- found.push(
142
- unreadableInstalled({
143
- dir,
144
- name,
145
- profile,
146
- manifestPath,
147
- message: `${manifestPath} is missing, so the installed copy has no manifest to read`,
148
- }),
149
- );
138
+ // Read the declarations before looking at node_modules: a declared bundle
139
+ // whose folder is gone is exactly the case this scan must not omit.
140
+ const declared = new Set(
141
+ readProfileBundles({ home, profile }).bundles.filter((name) => typeof name === 'string' && name.trim() !== ''),
142
+ );
143
+ const present = new Set();
144
+ if (fs.existsSync(modules) === true) {
145
+ for (const entry of fs.readdirSync(modules).sort()) {
146
+ if (entry.startsWith('.') === true) continue;
147
+ const candidates = entry.startsWith('@')
148
+ ? fs
149
+ .readdirSync(path.join(modules, entry))
150
+ .sort()
151
+ .map((name) => ({ dir: path.join(modules, entry, name), name: `${entry}/${name}` }))
152
+ : [{ dir: path.join(modules, entry), name: entry }];
153
+ for (const { dir, name } of candidates) {
154
+ if (declared.has(name) === true) present.add(name);
155
+ // A broken package.json is only evidence of a plugin when the profile
156
+ // says it mounts that name. Without that record an ordinary dependency
157
+ // whose install was interrupted must stay out of the audit, or one bad
158
+ // transitive package would turn every profile red.
159
+ const listedInProfile = declared.has(name) === true;
160
+ const manifestPath = path.join(dir, 'package.json');
161
+ if (fs.existsSync(manifestPath) === false) {
162
+ if (listedInProfile === true) {
163
+ found.push(
164
+ unreadableInstalled({
165
+ dir,
166
+ name,
167
+ profile,
168
+ manifestPath,
169
+ message: `${manifestPath} is missing, so the installed copy has no manifest to read`,
170
+ }),
171
+ );
172
+ }
173
+ continue;
150
174
  }
151
- continue;
152
- }
153
- let manifest;
154
- try {
155
- // Strip the BOM the same way doctor does: a manifest saved by Notepad
156
- // is still readable, and treating it as unreadable would be a false
157
- // alarm in the other direction.
158
- const text = String(fs.readFileSync(manifestPath, 'utf8')).replace(/^\uFEFF/u, '').trim();
159
- manifest = JSON.parse(text);
160
- } catch (error) {
161
- // A package.json that is listed in the profile but does not parse is
162
- // still an installed plugin, and "it does not parse" is exactly what
163
- // the author needs to hear.
164
- if (listedInProfile === true) {
165
- found.push(
166
- unreadableInstalled({
167
- dir,
168
- name,
169
- profile,
170
- manifestPath,
171
- message: `${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
172
- }),
173
- );
175
+ let manifest;
176
+ 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);
182
+ } catch (error) {
183
+ // A package.json that is listed in the profile but does not parse is
184
+ // still an installed plugin, and "it does not parse" is exactly what
185
+ // the author needs to hear.
186
+ if (listedInProfile === true) {
187
+ found.push(
188
+ unreadableInstalled({
189
+ dir,
190
+ name,
191
+ profile,
192
+ manifestPath,
193
+ message: `${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
194
+ }),
195
+ );
196
+ }
197
+ continue;
174
198
  }
175
- continue;
176
- }
177
- if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest) === true) {
178
- if (listedInProfile === true) {
179
- found.push(
180
- unreadableInstalled({
181
- dir,
182
- name,
183
- profile,
184
- manifestPath,
185
- message: `${manifestPath} is readable JSON but not a package object, so its dsh field cannot be checked`,
186
- }),
187
- );
199
+ if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest) === true) {
200
+ if (listedInProfile === true) {
201
+ found.push(
202
+ unreadableInstalled({
203
+ dir,
204
+ name,
205
+ profile,
206
+ manifestPath,
207
+ message: `${manifestPath} is readable JSON but not a package object, so its dsh field cannot be checked`,
208
+ }),
209
+ );
210
+ }
211
+ continue;
188
212
  }
189
- continue;
213
+ // Only packages that declare themselves as plugins. node_modules is full
214
+ // of ordinary dependencies, and auditing those is noise.
215
+ if (manifest.dsh === undefined) continue;
216
+ found.push({ dir, manifest, profile });
190
217
  }
191
- // Only packages that declare themselves as plugins. node_modules is full
192
- // of ordinary dependencies, and auditing those is noise.
193
- if (manifest.dsh === undefined) continue;
194
- found.push({ dir, manifest, profile });
195
218
  }
196
219
  }
220
+
221
+ // A name can stay in `dsh.profile.bundles` after its folder is removed (an
222
+ // interrupted install, a deleted package). The loader still tries to mount
223
+ // it, so the audit reports the missing install instead of leaving only the
224
+ // healthy siblings visible.
225
+ for (const name of declared) {
226
+ if (present.has(name) === true) continue;
227
+ const dir = path.join(modules, name);
228
+ if (fs.existsSync(dir) === true) continue;
229
+ found.push(missingInstalled({ dir, name, profile }));
230
+ }
197
231
  }
198
232
  return found;
199
233
  }
@@ -737,9 +771,13 @@ export async function audit({
737
771
  }
738
772
 
739
773
  const profileFiles = new Map();
740
- const rows = installed.map(({ dir, manifest, profile, manifestPath, unreadable = false, error }) => {
774
+ const rows = installed.map(({ dir, manifest, profile, manifestPath, unreadable = false, missing = false, error }) => {
741
775
  let failures;
742
- if (unreadable === true) {
776
+ if (missing === true) {
777
+ // The folder is gone, so there is no manifest for doctor to read. The
778
+ // profile record is the evidence, and the row must name the absent path.
779
+ failures = [{ check: 'install', message: error }];
780
+ } else if (unreadable === true) {
743
781
  // doctor would throw on the same file; keep the read error the install
744
782
  // scan already recorded so the row names the unreadable package.json.
745
783
  failures = [{ check: 'manifest', message: error }];
@@ -752,7 +790,12 @@ export async function audit({
752
790
  }
753
791
  const loaded = graph?.ok === true ? graph.ids.has(manifest.name) : null;
754
792
  let explanation = null;
755
- if (unreadable === true) {
793
+ if (missing === true) {
794
+ explanation = {
795
+ reason: `dsh.profile.bundles lists it, but ${dir} is missing, so there is no installed copy to mount`,
796
+ action: `reinstall ${manifest.name} (for example \`dsh plugin add ${manifest.name}\`), then restart the app`,
797
+ };
798
+ } else if (unreadable === true) {
756
799
  explanation = {
757
800
  reason: `${manifestPath} is unreadable, so the loader cannot tell what to mount`,
758
801
  action: `reinstall ${manifest.name} so its package.json is written completely`,
@@ -778,6 +821,7 @@ export async function audit({
778
821
  ...split(failures),
779
822
  loaded,
780
823
  unreadable: unreadable === true,
824
+ missing: missing === true,
781
825
  reason: explanation?.reason ?? null,
782
826
  action: explanation?.action ?? null,
783
827
  };
@@ -787,11 +831,21 @@ export async function audit({
787
831
  const detailIndent = ' '.repeat(width + 24);
788
832
  for (const row of rows) {
789
833
  const state =
790
- row.unreadable === true ? 'unreadable' : row.loaded === null ? '?' : row.loaded === true ? 'loaded' : 'not loaded';
791
- const reason = row.loaded === false || row.unreadable === true ? ` — ${row.reason}` : '';
834
+ row.missing === true
835
+ ? 'missing'
836
+ : row.unreadable === true
837
+ ? 'unreadable'
838
+ : row.loaded === null
839
+ ? '?'
840
+ : row.loaded === true
841
+ ? 'loaded'
842
+ : 'not loaded';
843
+ const reason = row.missing === true || row.loaded === false || row.unreadable === true ? ` — ${row.reason}` : '';
792
844
  io.log(`${row.name.padEnd(width)} ${String(row.version).padEnd(8)} ${state.padEnd(10)} ${describe(row)}${reason}`);
793
845
  for (const failure of row.failures) io.log(`${' '.repeat(width + 22)}${failure.check}: ${failure.message}`);
794
- if (row.loaded === false || row.unreadable === true) io.log(`${detailIndent}fix: ${row.action}`);
846
+ if (row.missing === true || row.loaded === false || row.unreadable === true) {
847
+ io.log(`${detailIndent}fix: ${row.action}`);
848
+ }
795
849
  }
796
850
 
797
851
  const failed = rows.filter((row) => row.hard.length > 0);
package/lib/doctor.mjs CHANGED
@@ -484,9 +484,34 @@ export function checkRootExport(dir, manifest) {
484
484
  return `exports["."] points at the CLI (${entry}), so the loader's row has no plugin to apply; point it at the module that exports apply`;
485
485
  }
486
486
 
487
+ // A root that cannot be loaded is the same failure as one that exports no
488
+ // apply: the loader imports the bare package name and the row mounts nothing.
489
+ // Missing files and directories are the two shapes a manifest actually ships
490
+ // by accident, and the directory case used to escape as a raw EISDIR. Ask
491
+ // the filesystem what the path is before reading it, so a directory, a
492
+ // broken symlink and an unreadable file all become a named check failure.
487
493
  const file = path.resolve(dir, target);
488
- if (fs.existsSync(file) === false) return null;
489
- const source = fs.readFileSync(file, 'utf8');
494
+ let stat;
495
+ try {
496
+ stat = fs.statSync(file);
497
+ } catch (error) {
498
+ if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
499
+ return `the root export ${entry} does not exist, so the loader cannot import the package`;
500
+ }
501
+ return `the root export ${entry} cannot be read (${error?.code ?? 'filesystem error'}), so the loader cannot import the package`;
502
+ }
503
+ if (stat.isDirectory() === true) {
504
+ return `the root export ${entry} is a directory, not a module, so the loader cannot import it`;
505
+ }
506
+ if (stat.isFile() === false) {
507
+ return `the root export ${entry} is not a regular file, so the loader cannot import it`;
508
+ }
509
+ let source;
510
+ try {
511
+ source = fs.readFileSync(file, 'utf8');
512
+ } catch (error) {
513
+ return `the root export ${entry} cannot be read (${error?.code ?? 'filesystem error'}), so the loader cannot import it`;
514
+ }
490
515
  if (exportsApply(source) === false) {
491
516
  return `the root export ${entry} does not export apply, so the loader imports the package and mounts nothing`;
492
517
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.15",
3
+ "version": "0.20.17",
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": {