dsh-plugin-toolkit 0.20.30 → 0.20.32
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 +34 -0
- package/README.md +9 -1
- package/lib/cli.mjs +130 -17
- package/lib/verify.mjs +16 -3
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,37 @@
|
|
|
1
|
+
## 0.20.32
|
|
2
|
+
|
|
3
|
+
- **Every value-taking flag rejects a missing value instead of falling back to
|
|
4
|
+
a default or swallowing the next option.** `--range`, `--log`, `--tag-prefix`,
|
|
5
|
+
`--base`, `--market`, `--timeout`, `--debounce`, `--slot`, `--surface`,
|
|
6
|
+
`--dest`, `--entry`, `--build`, `--title` and `--name` share the guard
|
|
7
|
+
`--index`, `--host` and `--home` already had. Before this, `fix --engines
|
|
8
|
+
--range --write` stored `--write` as the range and failed later with a semver
|
|
9
|
+
error, while `release --dry-run --tag-prefix` silently planned the default
|
|
10
|
+
`plugin-v` prefix. Each now exits `2`, names the flag, and stops before
|
|
11
|
+
reading a file or planning a release. A valid value still reaches the
|
|
12
|
+
command, and `test/value-flag-contract.test.mjs` pins the whole family at the
|
|
13
|
+
process boundary.
|
|
14
|
+
|
|
15
|
+
## 0.20.31
|
|
16
|
+
|
|
17
|
+
- **`index --index` with no path is a usage error, not a silent default.** A
|
|
18
|
+
bare `--index` used to store `undefined`, so the command read
|
|
19
|
+
`./market/index.json` and could exit `0` on an index the caller never named;
|
|
20
|
+
a CI step could therefore go green against the wrong file. The flag parser
|
|
21
|
+
now records the missing value separately, and the CLI exits `2` with
|
|
22
|
+
`--index` named before any index is read. A named path, whether
|
|
23
|
+
`--index market/index.json` or the positional form, still audits that file.
|
|
24
|
+
|
|
25
|
+
- **`verify` also awaits an async client `apply()` on its boot probe.** The
|
|
26
|
+
host half was made safe first; the mounted path then handed the client face a
|
|
27
|
+
bare context without waiting for the returned promise. A client `async
|
|
28
|
+
apply()` that rejected on that context escaped the probe, so the process died
|
|
29
|
+
with an unhandled rejection and a stack trace instead of naming the failure.
|
|
30
|
+
The probe now awaits the same way as the host, so the rejection is a `boot`
|
|
31
|
+
failure naming the error. An async client fixture pins the process boundary,
|
|
32
|
+
and a non-`Error` rejection now reports its value instead of `undefined` or a
|
|
33
|
+
second TypeError from reading `.message`.
|
|
34
|
+
|
|
1
35
|
## 0.20.30
|
|
2
36
|
|
|
3
37
|
- **The compatibility sample is the shipped CLI's output, not a library
|
package/README.md
CHANGED
|
@@ -948,7 +948,7 @@ ok packed 5 file(s), installed the tarball, mounted the panel
|
|
|
948
948
|
My panel This panel came from dsh-plugin init. Clicks: 0
|
|
949
949
|
```
|
|
950
950
|
|
|
951
|
-
It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. The host half is imported by the package's bare name, exactly as the loader imports it, so an `exports` map with no `.` entry fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` even when `main` names a working file; `verify --no-mount` reports that as a `root export` failure naming the missing `.` export. The host half is also called and awaited, so an `async apply()` that rejects is reported as a `host apply` failure instead of printing the success line and then crashing with an unhandled rejection. A package that declares neither `exports` nor `main` has no root module at all; there is nothing to import, and the success line says it skipped the host import instead of claiming one ran. When the `files` list drops the panel:
|
|
951
|
+
It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. The host half is imported by the package's bare name, exactly as the loader imports it, so an `exports` map with no `.` entry fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` even when `main` names a working file; `verify --no-mount` reports that as a `root export` failure naming the missing `.` export. The host half is also called and awaited, so an `async apply()` that rejects is reported as a `host apply` failure instead of printing the success line and then crashing with an unhandled rejection; the client half's boot probe is awaited the same way, so an async `apply()` that rejects on the bare context is a `boot` failure. A package that declares neither `exports` nor `main` has no root module at all; there is nothing to import, and the success line says it skipped the host import instead of claiming one ran. When the `files` list drops the panel:
|
|
952
952
|
|
|
953
953
|
```sh
|
|
954
954
|
$ npx dsh-plugin-toolkit verify .
|
|
@@ -1077,6 +1077,14 @@ merged
|
|
|
1077
1077
|
| 1 | A check failed, an installed plugin was not loaded by the running app, or the release stopped (the failing stage is named) |
|
|
1078
1078
|
| 2 | Unknown command, invalid usage, or a remote request that could not be completed |
|
|
1079
1079
|
|
|
1080
|
+
A flag that takes a value must be given one. When `--range`, `--log`,
|
|
1081
|
+
`--tag-prefix`, `--base`, `--market`, `--timeout`, `--debounce`, `--slot`,
|
|
1082
|
+
`--surface`, `--dest`, `--entry`, `--build`, `--title`, `--name`, `--index`,
|
|
1083
|
+
`--host`, `--home`, `--budget`, `--patch`, `--from`, `--jobs` or `--patch-dir`
|
|
1084
|
+
is the last token, or is followed by another flag, the command exits `2` and
|
|
1085
|
+
names the flag instead of falling back to a default or consuming the next
|
|
1086
|
+
option as the value.
|
|
1087
|
+
|
|
1080
1088
|
`fix <owner>/<repo> --remote` exits `0` both when it prints a diff for a missing
|
|
1081
1089
|
`engines.dsh` and when the manifest already declares a range that clears the
|
|
1082
1090
|
check; the second case prints `ok ... nothing to apply` and writes no diff.
|
package/lib/cli.mjs
CHANGED
|
@@ -116,24 +116,75 @@ Flags
|
|
|
116
116
|
--force with init: write into a directory that is not empty; with fix --remote --patch or audit --patch-dir: overwrite an existing patch file
|
|
117
117
|
`;
|
|
118
118
|
|
|
119
|
+
const MISSING_VALUE_MESSAGES = {
|
|
120
|
+
'--range': '--range needs a semver range, for example --range ">=0.3.0 <1.0.0"',
|
|
121
|
+
'--log': '--log needs a log file path, for example --log ~/.dsh/logs/install.log',
|
|
122
|
+
'--tag-prefix': '--tag-prefix needs a prefix, for example --tag-prefix plugin-v',
|
|
123
|
+
'--base': '--base needs a branch name, for example --base main',
|
|
124
|
+
'--market': '--market needs a checkout path, for example --market ../market-repo',
|
|
125
|
+
'--timeout': '--timeout needs a number of milliseconds',
|
|
126
|
+
'--debounce': '--debounce needs a number of milliseconds',
|
|
127
|
+
'--slot': '--slot needs a slot name, for example --slot sidebar.right.pane.tab',
|
|
128
|
+
'--surface': '--surface needs a surface name, for example --surface sidebar',
|
|
129
|
+
'--dest': '--dest needs a directory path',
|
|
130
|
+
'--entry': '--entry needs a file path',
|
|
131
|
+
'--build': '--build needs a command, for example --build "npm run build"',
|
|
132
|
+
'--title': '--title needs a panel title, for example --title "My panel"',
|
|
133
|
+
};
|
|
134
|
+
|
|
119
135
|
function flags(argv) {
|
|
120
|
-
const parsed = { positional: [] };
|
|
136
|
+
const parsed = { positional: [], missingValues: [] };
|
|
121
137
|
for (let index = 0; index < argv.length; index += 1) {
|
|
122
138
|
const token = argv[index];
|
|
139
|
+
// A value-taking flag must be followed by its value, not by another flag or
|
|
140
|
+
// the end of the line. The old branches read `argv[++index]` unconditionally,
|
|
141
|
+
// so `--range --write` made `--write` the range and `--tag-prefix` silently
|
|
142
|
+
// fell back to the default. Remember the missing flag so `run()` can stop at
|
|
143
|
+
// usage validation before reading a file or planning a release.
|
|
144
|
+
const take = (flag) => {
|
|
145
|
+
const next = argv[index + 1];
|
|
146
|
+
if (next === undefined || next.startsWith('--') === true) {
|
|
147
|
+
parsed.missingValues.push(flag);
|
|
148
|
+
return null;
|
|
149
|
+
}
|
|
150
|
+
index += 1;
|
|
151
|
+
return next;
|
|
152
|
+
};
|
|
123
153
|
if (token === '--dry-run') parsed.dryRun = true;
|
|
124
154
|
else if (token === '--engines') parsed.engines = true;
|
|
125
155
|
else if (token === '--fix') parsed.fix = true;
|
|
126
156
|
else if (token === '--write') parsed.write = true;
|
|
127
|
-
else if (token === '--range')
|
|
157
|
+
else if (token === '--range') {
|
|
158
|
+
const value = take('--range');
|
|
159
|
+
if (value !== null) parsed.range = value;
|
|
160
|
+
}
|
|
128
161
|
else if (token === '--patch') {
|
|
129
162
|
// Leave the value blank when the next token is another flag; the fix
|
|
130
163
|
// branch reports the missing path instead of swallowing that flag.
|
|
131
164
|
const next = argv[index + 1];
|
|
132
165
|
parsed.patch = next === undefined || next.startsWith('--') === true ? '' : argv[++index];
|
|
133
166
|
}
|
|
134
|
-
else if (token === '--log')
|
|
135
|
-
|
|
136
|
-
|
|
167
|
+
else if (token === '--log') {
|
|
168
|
+
const value = take('--log');
|
|
169
|
+
if (value !== null) parsed.log = value;
|
|
170
|
+
}
|
|
171
|
+
else if (token === '--index') {
|
|
172
|
+
// A bare `--index` is a missing path, not a request for the default. The
|
|
173
|
+
// `index` command used to fall back to ./market/index.json and exit 0,
|
|
174
|
+
// so a CI step could go green on a different index than the one it
|
|
175
|
+
// named. Remember the missing value apart from the path itself, so the
|
|
176
|
+
// command can stop before reading any index.
|
|
177
|
+
const next = argv[index + 1];
|
|
178
|
+
if (next === undefined || next.startsWith('--') === true) {
|
|
179
|
+
parsed.indexMissing = true;
|
|
180
|
+
} else {
|
|
181
|
+
parsed.index = argv[++index];
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
else if (token === '--tag-prefix') {
|
|
185
|
+
const value = take('--tag-prefix');
|
|
186
|
+
if (value !== null) parsed.tagPrefix = value;
|
|
187
|
+
}
|
|
137
188
|
else if (token === '--budget') {
|
|
138
189
|
// A budget of `8m`, `0`, or `-1` is not a wait, and by the time the
|
|
139
190
|
// registry loop notices, the tag is already pushed. Validate the flag
|
|
@@ -146,16 +197,40 @@ function flags(argv) {
|
|
|
146
197
|
parsed.budget = seconds;
|
|
147
198
|
}
|
|
148
199
|
}
|
|
149
|
-
else if (token === '--slot')
|
|
150
|
-
|
|
200
|
+
else if (token === '--slot') {
|
|
201
|
+
const value = take('--slot');
|
|
202
|
+
if (value !== null) parsed.slot = value;
|
|
203
|
+
}
|
|
204
|
+
else if (token === '--surface') {
|
|
205
|
+
const value = take('--surface');
|
|
206
|
+
if (value !== null) parsed.surface = value;
|
|
207
|
+
}
|
|
151
208
|
else if (token === '--html') parsed.html = true;
|
|
152
|
-
else if (token === '--name')
|
|
153
|
-
|
|
209
|
+
else if (token === '--name') {
|
|
210
|
+
// The init branch already has a precise "required" message; remember a
|
|
211
|
+
// missing value so a following flag is not consumed as the package name.
|
|
212
|
+
const next = argv[index + 1];
|
|
213
|
+
if (next === undefined || next.startsWith('--') === true) parsed.nameMissing = true;
|
|
214
|
+
else parsed.name = argv[++index];
|
|
215
|
+
}
|
|
216
|
+
else if (token === '--title') {
|
|
217
|
+
const value = take('--title');
|
|
218
|
+
if (value !== null) parsed.title = value;
|
|
219
|
+
}
|
|
154
220
|
else if (token === '--force') parsed.force = true;
|
|
155
221
|
else if (token === '--no-mount') parsed.noMount = true;
|
|
156
|
-
else if (token === '--dest')
|
|
157
|
-
|
|
158
|
-
|
|
222
|
+
else if (token === '--dest') {
|
|
223
|
+
const value = take('--dest');
|
|
224
|
+
if (value !== null) parsed.dest = value;
|
|
225
|
+
}
|
|
226
|
+
else if (token === '--entry') {
|
|
227
|
+
const value = take('--entry');
|
|
228
|
+
if (value !== null) parsed.entry = value;
|
|
229
|
+
}
|
|
230
|
+
else if (token === '--build') {
|
|
231
|
+
const value = take('--build');
|
|
232
|
+
if (value !== null) parsed.build = value;
|
|
233
|
+
}
|
|
159
234
|
else if (token === '--host') {
|
|
160
235
|
// A bare `--host` is a missing value, not permission to swallow the next
|
|
161
236
|
// flag. `audit --remote --host --json` used to compare every repository
|
|
@@ -197,8 +272,14 @@ function flags(argv) {
|
|
|
197
272
|
else if (value !== true) parsed.remote = parsed.remote === true ? value : `${parsed.remote},${value}`;
|
|
198
273
|
} else if (token === '--json') parsed.json = true;
|
|
199
274
|
else if (token === '--once') parsed.once = true;
|
|
200
|
-
else if (token === '--debounce')
|
|
201
|
-
|
|
275
|
+
else if (token === '--debounce') {
|
|
276
|
+
const value = take('--debounce');
|
|
277
|
+
if (value !== null) parsed.debounce = Number(value);
|
|
278
|
+
}
|
|
279
|
+
else if (token === '--timeout') {
|
|
280
|
+
const value = take('--timeout');
|
|
281
|
+
if (value !== null) parsed.timeout = Number(value);
|
|
282
|
+
}
|
|
202
283
|
else if (token === '--pr') parsed.pr = true;
|
|
203
284
|
else if (token === '--merge') parsed.merge = true;
|
|
204
285
|
else if (token === '--publish') parsed.publish = true;
|
|
@@ -216,8 +297,14 @@ function flags(argv) {
|
|
|
216
297
|
parsed.home = argv[++index];
|
|
217
298
|
}
|
|
218
299
|
}
|
|
219
|
-
else if (token === '--base')
|
|
220
|
-
|
|
300
|
+
else if (token === '--base') {
|
|
301
|
+
const value = take('--base');
|
|
302
|
+
if (value !== null) parsed.base = value;
|
|
303
|
+
}
|
|
304
|
+
else if (token === '--market') {
|
|
305
|
+
const value = take('--market');
|
|
306
|
+
if (value !== null) parsed.market = value;
|
|
307
|
+
}
|
|
221
308
|
else if (token.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
|
|
222
309
|
else parsed.positional.push(token);
|
|
223
310
|
}
|
|
@@ -255,6 +342,32 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
255
342
|
return 0;
|
|
256
343
|
}
|
|
257
344
|
|
|
345
|
+
// `--name` has its own required-argument wording, but a following option is
|
|
346
|
+
// still a missing value rather than the package name.
|
|
347
|
+
if (options.nameMissing === true) {
|
|
348
|
+
io.error('dsh-plugin init: --name <package-name> is required');
|
|
349
|
+
return 2;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
// Every value-taking flag is validated here, before a command can read a
|
|
353
|
+
// file, plan a release, or consume the next option as its value. A missing
|
|
354
|
+
// value is invalid usage, not a request for the flag's default.
|
|
355
|
+
if (options.missingValues.length > 0) {
|
|
356
|
+
const flag = options.missingValues[0];
|
|
357
|
+
const message = MISSING_VALUE_MESSAGES[flag] ?? `${flag} needs a value`;
|
|
358
|
+
io.error(`dsh-plugin ${command}: ${message}`);
|
|
359
|
+
return 2;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
// `--index` names the file to audit or update. Without a value the `index`
|
|
363
|
+
// command used to read ./market/index.json and exit 0, which let a CI step
|
|
364
|
+
// pass against an index the caller never named. Reject the usage error here,
|
|
365
|
+
// before any command can read or write an index.
|
|
366
|
+
if (options.indexMissing === true || (options.index !== undefined && String(options.index).trim() === '')) {
|
|
367
|
+
io.error('dsh-plugin --index needs a path to an index file, for example: dsh-plugin index market/index.json');
|
|
368
|
+
return 2;
|
|
369
|
+
}
|
|
370
|
+
|
|
258
371
|
// `--host` means a URL for a local audit and a DSH version for a remote one,
|
|
259
372
|
// so a bare flag must stop before either reads anything. Otherwise the audit
|
|
260
373
|
// silently omits the compatibility answer the user asked for.
|
|
@@ -541,7 +654,7 @@ export async function run(argv, io = console, deps = {}) {
|
|
|
541
654
|
}
|
|
542
655
|
|
|
543
656
|
if (command === 'init') {
|
|
544
|
-
if (options.name === undefined) {
|
|
657
|
+
if (options.name === undefined || options.nameMissing === true) {
|
|
545
658
|
io.error('dsh-plugin init: --name <package-name> is required');
|
|
546
659
|
return 2;
|
|
547
660
|
}
|
package/lib/verify.mjs
CHANGED
|
@@ -80,6 +80,16 @@ function undeclaredContext() {
|
|
|
80
80
|
});
|
|
81
81
|
}
|
|
82
82
|
|
|
83
|
+
/**
|
|
84
|
+
* A rejected `apply()` is not required to reject with an Error. Reading
|
|
85
|
+
* `.message` off a string (or `null`) either reports `undefined` or throws a
|
|
86
|
+
* second TypeError inside the handler, which hides the plugin's own reason.
|
|
87
|
+
*/
|
|
88
|
+
function failureText(error) {
|
|
89
|
+
if (error instanceof Error) return error.message;
|
|
90
|
+
return String(error);
|
|
91
|
+
}
|
|
92
|
+
|
|
83
93
|
/**
|
|
84
94
|
* A declared path can be a pattern: `exports["./locale/*.json"]` names a folder
|
|
85
95
|
* of files, and `npm pack` lists the files it actually shipped. Exact set
|
|
@@ -292,7 +302,7 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
|
|
|
292
302
|
stage: 'install',
|
|
293
303
|
failures: [{
|
|
294
304
|
check: 'host apply',
|
|
295
|
-
message: `apply() throws when a service it never declared is read, which fails the row (a rejecting async apply is awaited the same way): ${error
|
|
305
|
+
message: `apply() throws when a service it never declared is read, which fails the row (a rejecting async apply is awaited the same way): ${failureText(error)}`,
|
|
296
306
|
}],
|
|
297
307
|
files: packed.files,
|
|
298
308
|
};
|
|
@@ -332,9 +342,12 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
|
|
|
332
342
|
faceProblems.push('the client module declares no inject list, so the loader calls apply() before its services exist');
|
|
333
343
|
}
|
|
334
344
|
try {
|
|
335
|
-
|
|
345
|
+
// An async client `apply()` rejects after the call returns, exactly like
|
|
346
|
+
// the host half. Awaiting it here keeps a late rejection inside this
|
|
347
|
+
// probe instead of letting it kill the process after the success line.
|
|
348
|
+
await face.apply(absentContext());
|
|
336
349
|
} catch (error) {
|
|
337
|
-
faceProblems.push(`apply() throws when the services are absent, which fails the web boot: ${error
|
|
350
|
+
faceProblems.push(`apply() throws when the services are absent, which fails the web boot (a rejecting async apply is awaited the same way): ${failureText(error)}`);
|
|
338
351
|
}
|
|
339
352
|
await panel.unmount();
|
|
340
353
|
if (faceProblems.length > 0) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-plugin-toolkit",
|
|
3
|
-
"version": "0.20.
|
|
3
|
+
"version": "0.20.32",
|
|
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": {
|