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/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 gitRun = options.git ?? ((args) => git(dir, args));
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(dir);
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(dir, tag, gitRun) === true;
152
- if (resuming === true && tagPointsAtHead(dir, tag, gitRun) === false) {
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(dir, tag, gitRun);
157
- const head = headCommit(dir, gitRun);
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(dir, gitRun) === false) {
174
- const dirty = dirtyPaths(dir, 3, gitRun);
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)(dir);
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
- const entry = buildEntry({ version, publishTimestamp: timestamp, hostRange: report.notes.hostRange });
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 ? path.resolve(marketDir) : dir;
241
- const indexPath = path.join(indexRoot, indexFile);
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 === dir ? options.git : ((args) => git(indexRoot, args)));
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 { isHostRange, renderManifest, resolveEnginesRange, unifiedDiff } from './fix.mjs';
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
- * Expand a leading `~` the way a POSIX shell would.
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) fail('readme', 'the repository has no README, so a reader cannot tell how to install it or what it needs');
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 current = hostRange(manifest);
543
- const correct = current !== null && checkHostRange(manifest) === null;
544
- const same = current !== null && current.trim() === proposed;
545
- const forced = force === true || requested.force === true;
546
- if (correct === true && (forced !== true || same === true)) {
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: requested.host,
560
- nextMajor: requested.nextMajor,
561
- why: requested.why,
554
+ host: planned.host,
555
+ nextMajor: planned.nextMajor,
556
+ why: planned.why,
562
557
  diff: '',
563
558
  };
564
559
  }
565
560
 
566
- const engines =
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: current === null ? 'missing' : correct === true ? 'different' : 'not-a-range',
602
- host: requested.host,
603
- nextMajor: requested.nextMajor,
604
- why: requested.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 report = doctor(dir);
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(dir);
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(dir, report.manifest);
150
+ const repoEntry = resolveEntry(root, report.manifest);
149
151
  if (repoEntry !== null) {
150
- const relative = path.relative(dir, repoEntry).split(path.sep).join('/');
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.12",
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
- latency: BENCHMARK_LATENCY_MS,
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.latency = positive(flag, value);
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
  }