dsh-plugin-toolkit 0.20.12 → 0.20.14
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 +101 -0
- package/README.md +116 -37
- package/examples/compatibility-sample/README.md +11 -2
- package/examples/compatibility-sample/package.json +1 -1
- package/lib/audit.mjs +8 -5
- package/lib/benchmark.mjs +42 -6
- package/lib/cli.mjs +28 -11
- package/lib/compat.mjs +14 -7
- package/lib/dev.mjs +15 -11
- package/lib/doctor.mjs +213 -16
- package/lib/fix.mjs +66 -28
- package/lib/github.mjs +4 -3
- package/lib/index-file.mjs +3 -2
- package/lib/init.mjs +8 -3
- package/lib/paths.mjs +38 -0
- package/lib/release.mjs +27 -15
- package/lib/remote.mjs +39 -49
- package/lib/verify.mjs +7 -5
- package/package.json +1 -1
- package/scripts/benchmark-audit.mjs +2 -2
package/lib/paths.mjs
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* User-supplied paths, before they reach the filesystem.
|
|
3
|
+
*
|
|
4
|
+
* A POSIX shell expands `~/my-panel` before the program starts. `cmd` and
|
|
5
|
+
* PowerShell do not: they hand the literal string to the program, so
|
|
6
|
+
* `path.resolve('~/my-panel')` quietly creates a directory literally named `~`
|
|
7
|
+
* in the current working directory. Every command that accepts a folder or a
|
|
8
|
+
* file from a person has to expand the tilde itself, or the documented example
|
|
9
|
+
* writes somewhere surprising on Windows.
|
|
10
|
+
*/
|
|
11
|
+
import os from 'node:os';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Expand a leading `~` the way a POSIX shell would.
|
|
16
|
+
*
|
|
17
|
+
* `~\x` is the Windows spelling of a child path, so both separators are
|
|
18
|
+
* treated as separators here; `path.join` then uses the host one. `~someone`
|
|
19
|
+
* is a different user, not this home directory, and is left alone.
|
|
20
|
+
*/
|
|
21
|
+
export function expandHome(value, home = os.homedir()) {
|
|
22
|
+
const text = String(value ?? '').trim();
|
|
23
|
+
if (text === '' || /^~($|[\\/])/u.test(text) === false) {
|
|
24
|
+
return text;
|
|
25
|
+
}
|
|
26
|
+
const rest = text.slice(1).replace(/^[\\/]+/u, '').split(/[\\/]+/u).join('/');
|
|
27
|
+
return path.join(home, rest);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Expand a leading `~` and make the result absolute against the current
|
|
32
|
+
* working directory. This is the one step every filesystem-facing command
|
|
33
|
+
* applies to a user-named path, so `init`, `doctor`, `fix`, `verify`, `dev`,
|
|
34
|
+
* `release` and the audit flags all resolve the same way.
|
|
35
|
+
*/
|
|
36
|
+
export function resolvePath(value, { home = os.homedir(), cwd = process.cwd() } = {}) {
|
|
37
|
+
return path.resolve(cwd, expandHome(value, home));
|
|
38
|
+
}
|
package/lib/release.mjs
CHANGED
|
@@ -10,6 +10,7 @@ import fs from 'node:fs';
|
|
|
10
10
|
import path from 'node:path';
|
|
11
11
|
|
|
12
12
|
import { doctor } from './doctor.mjs';
|
|
13
|
+
import { expandHome, resolvePath } from './paths.mjs';
|
|
13
14
|
import { addVersion, buildEntry, readIndex, writeIndex } from './index-file.mjs';
|
|
14
15
|
import { publishedAt, waitForVersion } from './registry.mjs';
|
|
15
16
|
import { defaultGh, mergePr, openIndexPr, waitForChecks } from './pr.mjs';
|
|
@@ -94,7 +95,7 @@ export function dirtyPaths(dir, limit = 3, run) {
|
|
|
94
95
|
* and the exact commands.
|
|
95
96
|
*/
|
|
96
97
|
export function plan({ dir = process.cwd(), version, name, tagPrefix = 'plugin-v', indexFile = 'market/index.json', marketDir }) {
|
|
97
|
-
const report = doctor(dir);
|
|
98
|
+
const report = doctor(resolvePath(dir));
|
|
98
99
|
const resolvedName = name ?? report.manifest.name ?? 'this-plugin';
|
|
99
100
|
const resolvedVersion = version ?? report.manifest.version ?? '0.0.0';
|
|
100
101
|
const tag = tagName(resolvedVersion, tagPrefix);
|
|
@@ -130,11 +131,13 @@ export async function release(options) {
|
|
|
130
131
|
onChange,
|
|
131
132
|
} = options;
|
|
132
133
|
|
|
133
|
-
const
|
|
134
|
+
const root = resolvePath(dir);
|
|
135
|
+
const indexPathFile = expandHome(indexFile);
|
|
136
|
+
const gitRun = options.git ?? ((args) => git(root, args));
|
|
134
137
|
|
|
135
138
|
let report;
|
|
136
139
|
try {
|
|
137
|
-
report = doctor(
|
|
140
|
+
report = doctor(root);
|
|
138
141
|
} catch (error) {
|
|
139
142
|
// A folder without package.json is a preflight failure, not a crash: the
|
|
140
143
|
// command's job is to say what is wrong, and a stack trace is not an answer.
|
|
@@ -148,13 +151,13 @@ export async function release(options) {
|
|
|
148
151
|
const version = report.manifest.version;
|
|
149
152
|
const tag = tagName(version, tagPrefix);
|
|
150
153
|
|
|
151
|
-
const resuming = tagExists(
|
|
152
|
-
if (resuming === true && tagPointsAtHead(
|
|
154
|
+
const resuming = tagExists(root, tag, gitRun) === true;
|
|
155
|
+
if (resuming === true && tagPointsAtHead(root, tag, gitRun) === false) {
|
|
153
156
|
// A tag at another commit is not a resume: moving it would rewrite what the
|
|
154
157
|
// earlier release published. Name where it points, where HEAD is, and the
|
|
155
158
|
// exact commands that remove it so the next attempt can tag this commit.
|
|
156
|
-
const target = tagCommit(
|
|
157
|
-
const head = headCommit(
|
|
159
|
+
const target = tagCommit(root, tag, gitRun);
|
|
160
|
+
const head = headCommit(root, gitRun);
|
|
158
161
|
const targetText = target ?? 'an unknown commit';
|
|
159
162
|
const headText = head ?? 'an unknown commit';
|
|
160
163
|
return {
|
|
@@ -170,8 +173,8 @@ export async function release(options) {
|
|
|
170
173
|
// A resume does not create a tag, so the clean-tree rule that protects the
|
|
171
174
|
// tag does not apply: the index write from a previous attempt is allowed to
|
|
172
175
|
// be the only uncommitted change.
|
|
173
|
-
if (workingTreeIsClean(
|
|
174
|
-
const dirty = dirtyPaths(
|
|
176
|
+
if (workingTreeIsClean(root, gitRun) === false) {
|
|
177
|
+
const dirty = dirtyPaths(root, 3, gitRun);
|
|
175
178
|
const listed = dirty.length > 0 ? ` (${dirty.join(', ')})` : '';
|
|
176
179
|
return {
|
|
177
180
|
ok: false,
|
|
@@ -188,7 +191,7 @@ export async function release(options) {
|
|
|
188
191
|
// the same command covers both kinds of repository.
|
|
189
192
|
if (options.publish === true) {
|
|
190
193
|
try {
|
|
191
|
-
(options.publishPackage ?? publishPackage)(
|
|
194
|
+
(options.publishPackage ?? publishPackage)(root);
|
|
192
195
|
} catch (error) {
|
|
193
196
|
const detail = String(error.stderr ?? error.message).trim().split('\n').slice(-1)[0];
|
|
194
197
|
return { ok: false, stage: 'publish', failures: [{ check: 'publish', message: `npm publish failed: ${detail}` }] };
|
|
@@ -234,11 +237,20 @@ export async function release(options) {
|
|
|
234
237
|
}
|
|
235
238
|
|
|
236
239
|
const timestamp = publishedAt(waited.document, version);
|
|
237
|
-
|
|
240
|
+
// Building the entry can fail before the index is even read (a malformed
|
|
241
|
+
// `engines.dsh` is normally caught by doctor, but a caller that reaches this
|
|
242
|
+
// point must still get a result, not an exception). Keep the failure in the
|
|
243
|
+
// same `index` stage as an `addVersion` rejection and never write anything.
|
|
244
|
+
let entry;
|
|
245
|
+
try {
|
|
246
|
+
entry = buildEntry({ version, publishTimestamp: timestamp, hostRange: report.notes.hostRange });
|
|
247
|
+
} catch (error) {
|
|
248
|
+
return { ok: false, stage: 'index', failures: [{ check: 'index', message: error.message }] };
|
|
249
|
+
}
|
|
238
250
|
// Most plugins are listed in someone else's index: `--market` points at a
|
|
239
251
|
// checkout of that repository, and the entry plus the pull request land there.
|
|
240
|
-
const indexRoot = typeof marketDir === 'string' && marketDir.length > 0 ?
|
|
241
|
-
const indexPath = path.join(indexRoot,
|
|
252
|
+
const indexRoot = typeof marketDir === 'string' && marketDir.length > 0 ? resolvePath(marketDir) : root;
|
|
253
|
+
const indexPath = path.join(indexRoot, indexPathFile);
|
|
242
254
|
let indexUpdate = null;
|
|
243
255
|
if (fs.existsSync(indexPath) === true) {
|
|
244
256
|
try {
|
|
@@ -272,11 +284,11 @@ export async function release(options) {
|
|
|
272
284
|
// a green CI and a merge; doing that by hand is where "forgot to open the PR"
|
|
273
285
|
// happens.
|
|
274
286
|
const ghRunner = options.gh ?? defaultGh(indexRoot);
|
|
275
|
-
const marketGit = options.marketGit ?? (indexRoot ===
|
|
287
|
+
const marketGit = options.marketGit ?? (indexRoot === root ? options.git : ((args) => git(indexRoot, args)));
|
|
276
288
|
const pull = await openIndexPr({
|
|
277
289
|
dir: indexRoot,
|
|
278
290
|
git: marketGit,
|
|
279
|
-
indexFile,
|
|
291
|
+
indexFile: indexPathFile,
|
|
280
292
|
version,
|
|
281
293
|
base: options.base ?? 'main',
|
|
282
294
|
branch: options.branch,
|
package/lib/remote.mjs
CHANGED
|
@@ -14,20 +14,23 @@
|
|
|
14
14
|
* network call is injectable so the tests never touch GitHub.
|
|
15
15
|
*/
|
|
16
16
|
import fs from 'node:fs';
|
|
17
|
-
import os from 'node:os';
|
|
18
17
|
import path from 'node:path';
|
|
19
18
|
|
|
19
|
+
import { expandHome } from './paths.mjs';
|
|
20
20
|
import {
|
|
21
|
+
checkDshField,
|
|
21
22
|
checkFilesList,
|
|
22
23
|
checkHostCompatibility,
|
|
23
24
|
checkHostRange,
|
|
25
|
+
checkName,
|
|
26
|
+
checkReadmeText,
|
|
24
27
|
checkVersion,
|
|
25
28
|
exportTarget,
|
|
26
29
|
exportsApply,
|
|
27
30
|
hostRange,
|
|
28
31
|
rootEntry,
|
|
29
32
|
} from './doctor.mjs';
|
|
30
|
-
import {
|
|
33
|
+
import { planEnginesEdit, renderManifest, unifiedDiff } from './fix.mjs';
|
|
31
34
|
import { parseTarget as classifyTarget } from './github.mjs';
|
|
32
35
|
|
|
33
36
|
const API = 'https://api.github.com';
|
|
@@ -116,25 +119,9 @@ function resetSentence(info) {
|
|
|
116
119
|
*/
|
|
117
120
|
const UNREADABLE = Symbol('unreadable');
|
|
118
121
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
* `--patch ~/repair.patch` is the obvious way to write the example, and on
|
|
123
|
-
* Windows `cmd`/PowerShell leave the tilde alone, so `path.resolve('~/x')`
|
|
124
|
-
* quietly creates a directory literally named `~` inside the current working
|
|
125
|
-
* directory. Expanding here keeps the documented example working on every
|
|
126
|
-
* platform the plugin runs on.
|
|
127
|
-
*/
|
|
128
|
-
export function expandHome(value, home = os.homedir()) {
|
|
129
|
-
const text = String(value ?? '').trim();
|
|
130
|
-
if (text === '' || /^~($|[\\/])/u.test(text) === false) {
|
|
131
|
-
return text;
|
|
132
|
-
}
|
|
133
|
-
// `~\x` only ever means the Windows spelling of a child path, so treat
|
|
134
|
-
// both separators as separators here; path.join then uses the host one.
|
|
135
|
-
const rest = text.slice(1).replace(/^[\\/]+/u, '').split(/[\\/]+/u).join('/');
|
|
136
|
-
return path.join(home, rest);
|
|
137
|
-
}
|
|
122
|
+
// `expandHome` used to live here, and the path tests import it from this
|
|
123
|
+
// module. Keep that export while the shared implementation lives in paths.mjs.
|
|
124
|
+
export { expandHome };
|
|
138
125
|
|
|
139
126
|
|
|
140
127
|
/**
|
|
@@ -370,9 +357,15 @@ export async function auditRemote(
|
|
|
370
357
|
});
|
|
371
358
|
}
|
|
372
359
|
|
|
360
|
+
checked.push(['name', checkName(manifest)]);
|
|
373
361
|
checked.push(['version', checkVersion(manifest)]);
|
|
374
362
|
const enginesCheck = checkHostRange(manifest);
|
|
375
363
|
checked.push(['engines.dsh', enginesCheck]);
|
|
364
|
+
// `doctor` reads this field before it looks at the tree: a manifest with
|
|
365
|
+
// `dsh: {}` has no patch for the host to load, and the file checks below only
|
|
366
|
+
// find a missing patch when one is declared. Run the same manifest-only check
|
|
367
|
+
// here so a remote repository cannot pass with an empty `dsh` field.
|
|
368
|
+
checked.push(['dsh field', checkDshField(manifest)]);
|
|
376
369
|
checked.push(['files list', checkFilesList(manifest)]);
|
|
377
370
|
for (const [check, message] of checked) if (typeof message === 'string' && message.length > 0) fail(check, message);
|
|
378
371
|
|
|
@@ -455,8 +448,18 @@ export async function auditRemote(
|
|
|
455
448
|
}
|
|
456
449
|
}
|
|
457
450
|
|
|
451
|
+
// `doctor` reads the README text too: a repository can have a README with no
|
|
452
|
+
// Requirements section, or one that omits the host range it declares. Ask the
|
|
453
|
+
// same questions here so the remote verdict matches a checkout. A fallback
|
|
454
|
+
// `README` (no extension) is still read, but the shared message names
|
|
455
|
+
// README.md because that is the file the market convention expects.
|
|
458
456
|
const readme = (await exists('README.md')) ?? (await exists('README'));
|
|
459
|
-
if (readme === null)
|
|
457
|
+
if (readme === null) {
|
|
458
|
+
fail('readme', 'the repository has no README, so a reader cannot tell how to install it or what it needs');
|
|
459
|
+
} else if (readme !== UNREADABLE) {
|
|
460
|
+
const message = checkReadmeText(readme, manifest);
|
|
461
|
+
if (message !== null) fail('readme', message);
|
|
462
|
+
}
|
|
460
463
|
|
|
461
464
|
return withHost({
|
|
462
465
|
target: parsed,
|
|
@@ -506,15 +509,6 @@ export async function fixRemote(
|
|
|
506
509
|
) {
|
|
507
510
|
if (typeof fetchImpl !== 'function') throw new Error('fixRemote needs a fetch implementation');
|
|
508
511
|
const parsed = parseTarget(target);
|
|
509
|
-
const requested = resolveEnginesRange({ range, host });
|
|
510
|
-
if (requested.error !== undefined) {
|
|
511
|
-
throw new Error(requested.error);
|
|
512
|
-
}
|
|
513
|
-
const { proposed } = requested;
|
|
514
|
-
if (isHostRange(proposed) === false) {
|
|
515
|
-
throw new Error(`"${proposed}" is not a semver range, so it would not clear the doctor check`);
|
|
516
|
-
}
|
|
517
|
-
|
|
518
512
|
const patchPath =
|
|
519
513
|
patch === undefined || patch === null || String(patch).trim() === '' ? null : path.resolve(expandHome(patch));
|
|
520
514
|
if (patchPath !== null && overwrite !== true && fs.existsSync(patchPath)) {
|
|
@@ -539,11 +533,12 @@ export async function fixRemote(
|
|
|
539
533
|
throw new Error(`package.json at ${parsed.slug} does not hold a JSON object`);
|
|
540
534
|
}
|
|
541
535
|
|
|
542
|
-
const
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
536
|
+
const planned = planEnginesEdit(manifest, { range, host, force });
|
|
537
|
+
if (planned.ok !== true) {
|
|
538
|
+
throw new Error(planned.failures[0].message);
|
|
539
|
+
}
|
|
540
|
+
const { proposed, current } = planned;
|
|
541
|
+
if (planned.noop === true) {
|
|
547
542
|
return {
|
|
548
543
|
ok: true,
|
|
549
544
|
target: parsed,
|
|
@@ -556,19 +551,14 @@ export async function fixRemote(
|
|
|
556
551
|
patchPath,
|
|
557
552
|
patchWritten: false,
|
|
558
553
|
reason: 'already-correct',
|
|
559
|
-
host:
|
|
560
|
-
nextMajor:
|
|
561
|
-
why:
|
|
554
|
+
host: planned.host,
|
|
555
|
+
nextMajor: planned.nextMajor,
|
|
556
|
+
why: planned.why,
|
|
562
557
|
diff: '',
|
|
563
558
|
};
|
|
564
559
|
}
|
|
565
560
|
|
|
566
|
-
const
|
|
567
|
-
manifest.engines !== null && typeof manifest.engines === 'object' && Array.isArray(manifest.engines) === false
|
|
568
|
-
? manifest.engines
|
|
569
|
-
: {};
|
|
570
|
-
const next = { ...manifest, engines: { ...engines, dsh: proposed } };
|
|
571
|
-
const content = renderManifest(next, raw);
|
|
561
|
+
const content = renderManifest(planned.manifest, raw);
|
|
572
562
|
const diff = unifiedDiff(raw, content, { file: 'package.json' });
|
|
573
563
|
|
|
574
564
|
let patchWritten = false;
|
|
@@ -598,10 +588,10 @@ export async function fixRemote(
|
|
|
598
588
|
written: false,
|
|
599
589
|
patchPath,
|
|
600
590
|
patchWritten,
|
|
601
|
-
reason:
|
|
602
|
-
host:
|
|
603
|
-
nextMajor:
|
|
604
|
-
why:
|
|
591
|
+
reason: planned.reason,
|
|
592
|
+
host: planned.host,
|
|
593
|
+
nextMajor: planned.nextMajor,
|
|
594
|
+
why: planned.why,
|
|
605
595
|
diff,
|
|
606
596
|
};
|
|
607
597
|
}
|
package/lib/verify.mjs
CHANGED
|
@@ -13,6 +13,7 @@ import path from 'node:path';
|
|
|
13
13
|
|
|
14
14
|
import { doctor, declaredPaths, missingDeclaredPaths, rootEntry } from './doctor.mjs';
|
|
15
15
|
import { resolveEntry } from './dev.mjs';
|
|
16
|
+
import { resolvePath } from './paths.mjs';
|
|
16
17
|
import { run } from './exec.mjs';
|
|
17
18
|
|
|
18
19
|
function packJson(dir) {
|
|
@@ -114,7 +115,8 @@ function defersPatchToPack(report) {
|
|
|
114
115
|
}
|
|
115
116
|
|
|
116
117
|
export async function verify({ dir, mount = true }) {
|
|
117
|
-
const
|
|
118
|
+
const root = resolvePath(dir);
|
|
119
|
+
const report = doctor(root);
|
|
118
120
|
if (report.failures.length > 0 && defersPatchToPack(report) === false) {
|
|
119
121
|
return { ok: false, stage: 'doctor', failures: report.failures, files: [] };
|
|
120
122
|
}
|
|
@@ -122,7 +124,7 @@ export async function verify({ dir, mount = true }) {
|
|
|
122
124
|
|
|
123
125
|
let packed;
|
|
124
126
|
try {
|
|
125
|
-
packed = packJson(
|
|
127
|
+
packed = packJson(root);
|
|
126
128
|
} catch (error) {
|
|
127
129
|
return {
|
|
128
130
|
ok: false,
|
|
@@ -145,9 +147,9 @@ export async function verify({ dir, mount = true }) {
|
|
|
145
147
|
}
|
|
146
148
|
// The client bundle is usually found by convention (`client.js`), so it is
|
|
147
149
|
// not in `declaredPaths` — but it still has to be in the tarball.
|
|
148
|
-
const repoEntry = resolveEntry(
|
|
150
|
+
const repoEntry = resolveEntry(root, report.manifest);
|
|
149
151
|
if (repoEntry !== null) {
|
|
150
|
-
const relative = path.relative(
|
|
152
|
+
const relative = path.relative(root, repoEntry).split(path.sep).join('/');
|
|
151
153
|
if (shipsPath(shipped, relative) === false) {
|
|
152
154
|
failures.push({
|
|
153
155
|
check: 'pack',
|
|
@@ -160,7 +162,7 @@ export async function verify({ dir, mount = true }) {
|
|
|
160
162
|
|
|
161
163
|
const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-plugin-verify-'));
|
|
162
164
|
try {
|
|
163
|
-
return await inspectScratch({ dir, mount, report, packed, scratch });
|
|
165
|
+
return await inspectScratch({ dir: root, mount, report, packed, scratch });
|
|
164
166
|
} finally {
|
|
165
167
|
// Verify runs repeatedly in CI; leaving a full install tree behind each
|
|
166
168
|
// time fills the runner's disk. Remove it whether the run passed or failed.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-plugin-toolkit",
|
|
3
|
-
"version": "0.20.
|
|
3
|
+
"version": "0.20.14",
|
|
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": {
|
|
@@ -29,7 +29,7 @@ function positive(name, value) {
|
|
|
29
29
|
const options = {
|
|
30
30
|
list: BENCHMARK_LIST,
|
|
31
31
|
limit: BENCHMARK_LIMIT,
|
|
32
|
-
|
|
32
|
+
latencyMs: BENCHMARK_LATENCY_MS,
|
|
33
33
|
jobs: DEFAULT_JOBS,
|
|
34
34
|
};
|
|
35
35
|
|
|
@@ -50,7 +50,7 @@ for (let index = 0; index < argv.length; index += 1) {
|
|
|
50
50
|
index += 1;
|
|
51
51
|
if (flag === '--list') options.list = value;
|
|
52
52
|
else if (flag === '--limit') options.limit = positive(flag, value);
|
|
53
|
-
else if (flag === '--latency') options.
|
|
53
|
+
else if (flag === '--latency') options.latencyMs = positive(flag, value);
|
|
54
54
|
else if (flag === '--jobs') options.jobs = positive(flag, value);
|
|
55
55
|
else throw new Error(`unknown flag ${flag}; run with --help`);
|
|
56
56
|
}
|