dsh-plugin-toolkit 0.20.7 → 0.20.9

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,36 @@
1
+ ## 0.20.9
2
+
3
+ - **`dsh-plugin doctor` and `verify --no-mount` resolve a root export written as
4
+ a conditions object.** `exports["."]` can be a string or a conditions object
5
+ such as `{ "import": "./cli.mjs" }`; the loader still imports that target. It
6
+ used to be treated as "no root export", so a plugin whose conditions object
7
+ resolved to a CLI with no `apply` passed both checks. The failure now names
8
+ the resolved file, and a string root that exports `apply` still passes.
9
+ - **`verify --no-mount` no longer claims it imported a host half when it
10
+ skipped one.** A bundle that only inserts a subpath patch needs no root
11
+ module, so there is nothing for the loader to import. The success line used
12
+ to say "installed the tarball and imported its host half" anyway; it now says
13
+ the host import was skipped, so the line matches the check that actually ran.
14
+ - **`dsh-plugin explain --log` covers the Windows spelling of `~` and keeps a
15
+ missing log honest.** `~\.dsh\logs\install.log` expands the same way as
16
+ `~/.dsh/logs/install.log`, so the documented command works in PowerShell and
17
+ `cmd`; a log that cannot be read still exits `2` with the resolved absolute
18
+ path it tried, never a directory literally named `~`.
19
+
20
+ ## 0.20.8
21
+
22
+ - **`dsh-plugin release` resumes when the tag already points at HEAD.** A
23
+ publish that stopped after the tag was pushed — at the registry wait, or at a
24
+ later failure — can be re-run: the existing `plugin-v<version>` tag is reused
25
+ rather than recreated, and the release continues with the registry wait and
26
+ the index write. Because a resume creates no tag, the index entry left by the
27
+ previous attempt may be the only uncommitted change and does not block it.
28
+ - **`dsh-plugin release` refuses a tag at another commit and prints the
29
+ recovery.** When `plugin-v<version>` exists but points somewhere other than
30
+ HEAD, the release exits `1` with the tag, the commit it points at, HEAD, and
31
+ the exact `git tag -d` and `git push --delete` commands that remove the stale
32
+ tag before a re-run.
33
+
1
34
  ## 0.20.7
2
35
 
3
36
  - **`dsh-plugin release --budget` rejects a value that is not a positive
package/README.md CHANGED
@@ -844,6 +844,11 @@ $ npx dsh-plugin-toolkit explain "plugin install failed" ./my-panel
844
844
  The same checkout argument works after the log:
845
845
  `dsh-plugin explain --log ~/.dsh/logs/install.log ./my-panel`.
846
846
 
847
+ On Windows, `cmd` and PowerShell leave the tilde alone:
848
+ `--log ~\.dsh\logs\install.log` expands exactly like
849
+ `--log ~/.dsh/logs/install.log`. A log that cannot be read exits `2` and names
850
+ the resolved absolute path it tried, never a directory literally named `~`.
851
+
847
852
  Text it does not recognise exits `2` instead of guessing: a wrong diagnosis
848
853
  sends you editing the wrong file. A log with no known cause also exits `2` and
849
854
  lists the causes it looked for.
@@ -858,7 +863,7 @@ ok packed 5 file(s), installed the tarball, mounted the panel
858
863
  My panel This panel came from dsh-plugin init. Clicks: 0
859
864
  ```
860
865
 
861
- It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. When the `files` list drops the panel:
866
+ It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. A bundle that only inserts a subpath patch needs no root module; in that case 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:
862
867
 
863
868
  ```sh
864
869
  $ npx dsh-plugin-toolkit verify .
@@ -883,7 +888,9 @@ The install reports success and nothing shows up. In this order:
883
888
  node -e "import('my-plugin').then((m) => console.log(typeof m.apply))"
884
889
  ```
885
890
  `function` is what the loader needs. `undefined` means `exports["."]` points
886
- at the CLI — `0.8.0` of this tool shipped exactly that.
891
+ at the CLI — `0.8.0` of this tool shipped exactly that. A root written as a
892
+ conditions object (`{ "import": "./index.js" }`) is resolved before the
893
+ check, and `main` is only the fallback when no root export exists.
887
894
  3. **Does the tarball ship the panel?** `dsh-plugin verify .` installs what users
888
895
  get and mounts it. `doctor` cannot see this.
889
896
  4. **Is the patch row shaped right?** `cordis.patch.yml` needs one `- insert:`
@@ -903,7 +910,7 @@ The install reports success and nothing shows up. In this order:
903
910
  `release` runs the sequence in the order that fails cheapest first:
904
911
 
905
912
  1. Preflight (`doctor`) — stop before tagging anything.
906
- 2. Refuse to run on a dirty tree, or if the tag already exists.
913
+ 2. Refuse to run on a dirty tree. If the tag already exists and points at the current commit, reuse it and resume; if it points somewhere else, stop with the tag's commit and HEAD, and print the `git tag -d` / `git push --delete` recovery.
907
914
  3. Create and push the tag, which starts the plugin's release workflow.
908
915
  4. Poll the registry until it actually serves that version, reporting each wait.
909
916
  5. Write the index entry with the publish time **the registry reports**, not the local clock. It waits for `time[version]` specifically: the abbreviated registry document has no `time` field, and an entry with a null timestamp is rejected by the market checker.
@@ -921,7 +928,19 @@ checks settled after 1s (1 look(s))
921
928
  merged
922
929
  ```
923
930
 
924
- Without `--pr` it prints the `git add` / `gh pr create` commands instead of running them; `--dry-run` prints the whole sequence before anything happens. A re-run after a failure is safe: the same version with the same publish time is a no-op.
931
+ Without `--pr` it prints the `git add` / `gh pr create` commands instead of running them; `--dry-run` prints the whole sequence before anything happens. A re-run after a failure is safe: when the tag already points at HEAD it is reused rather than recreated, the release continues with the registry wait, and the same version with the same publish time is a no-op.
932
+
933
+ If that tag points at another commit, the release does not move it. It exits `1`
934
+ and names the tag, the commit it points at, HEAD, and the recovery:
935
+
936
+ ```
937
+ dsh-plugin release stopped at tag
938
+ ✗ tag: plugin-v0.4.0 already exists and does not point at HEAD: tag plugin-v0.4.0 is at <tag-sha>, HEAD is <head-sha>. Delete the stale tag with `git tag -d plugin-v0.4.0` and `git push --delete origin plugin-v0.4.0`, then re-run release.
939
+ ```
940
+
941
+ Run those two commands when the old tag really was a mistake, then release
942
+ again. A tag at HEAD needs no separate `--resume`: it takes the resume path
943
+ automatically.
925
944
 
926
945
  ### When nothing publishes for you
927
946
 
@@ -965,8 +984,19 @@ Honest list, so nobody plans around a feature that does not exist:
965
984
  ## Changelog
966
985
 
967
986
  [`CHANGELOG.md`](CHANGELOG.md) lists what changed in each release, including
968
- the `0.20.7` fix: `release --budget` rejects a value that is not a positive
969
- number of seconds — `8m`, `0`, `-1` or a missing value — with exit `2` before
987
+ the `0.20.9` fix: `explain --log` expands the Windows spelling
988
+ `~\.dsh\logs\install.log` exactly like `~/.dsh/logs/install.log`, so the
989
+ documented command works in PowerShell and `cmd`, and a log that cannot be read
990
+ exits `2` naming the resolved absolute path it tried instead of a directory
991
+ literally named `~`. The `0.20.8` fixes are recorded too: `release` resumes when
992
+ `plugin-v<version>` already points at
993
+ HEAD — reusing the tag and continuing to the registry wait instead of failing —
994
+ and refuses a tag at another commit, printing the tag, the commit it points at,
995
+ HEAD and the exact `git tag -d` / `git push --delete` recovery commands. A
996
+ resume does not recreate the tag, so an index entry left by the aborted run does
997
+ not block it. The `0.20.7` fix is recorded too: `release --budget` rejects a
998
+ value that is not a positive number of seconds — `8m`, `0`, `-1` or a missing
999
+ value — with exit `2` before
970
1000
  any local or remote tag is created, instead of pushing the tag and then waiting.
971
1001
  The `0.20.6` fixes are recorded too: `doctor` reads a `files` glob the way
972
1002
  `npm pack` does, so a `"files": ["*.js"]` entry no longer hides a nested
package/lib/cli.mjs CHANGED
@@ -8,7 +8,7 @@ import path from 'node:path';
8
8
 
9
9
  import { doctor } from './doctor.mjs';
10
10
  import { DEFAULT_ENGINES, doctorFix, fixEngines } from './fix.mjs';
11
- import { auditRemote, fixRemote } from './remote.mjs';
11
+ import { auditRemote, expandHome, fixRemote } from './remote.mjs';
12
12
  import { init } from './init.mjs';
13
13
  import { verify } from './verify.mjs';
14
14
  import { plan, release } from './release.mjs';
@@ -419,7 +419,7 @@ export async function run(argv, io = console, deps = {}) {
419
419
  let result;
420
420
 
421
421
  if (options.log !== undefined) {
422
- const logFile = path.resolve(options.log);
422
+ const logFile = path.resolve(expandHome(options.log));
423
423
  let log;
424
424
  try {
425
425
  log = fs.readFileSync(logFile, 'utf8');
@@ -475,7 +475,12 @@ export async function run(argv, io = console, deps = {}) {
475
475
  if (command === 'verify') {
476
476
  const result = await verify({ dir, mount: options.noMount !== true });
477
477
  if (result.ok === true) {
478
- const what = result.stage === 'mount' ? 'installed the tarball, mounted the panel' : 'installed the tarball and imported its host half';
478
+ const what =
479
+ result.stage === 'mount'
480
+ ? 'installed the tarball, mounted the panel'
481
+ : result.hostImported === true
482
+ ? 'installed the tarball and imported its host half'
483
+ : 'installed the tarball and skipped the host import, because there is no root export';
479
484
  io.log(`ok packed ${result.files.length} file(s), ${what}`);
480
485
  if (typeof result.text === 'string') io.log(` ${result.text}`);
481
486
  return 0;
package/lib/doctor.mjs CHANGED
@@ -123,12 +123,26 @@ export function checkPatchFile(dir, manifest) {
123
123
  return `dsh.bundle.patch points at ${bundle.patch}, which does not exist`;
124
124
  }
125
125
 
126
- /** `exports['./client']` is a string in some packages and a conditions object in others. */
126
+ /**
127
+ * `exports['./client']` is a string in some packages and a conditions object in
128
+ * others, and the root export can be either. Resolve the conditions Node or a
129
+ * bundler would use, including a nested object such as
130
+ * `{ node: { import: './index.mjs' } }`; an array's first resolvable
131
+ * alternative wins.
132
+ */
127
133
  export function exportTarget(value) {
128
134
  if (typeof value === 'string') return value;
135
+ if (Array.isArray(value)) {
136
+ for (const candidate of value) {
137
+ const target = exportTarget(candidate);
138
+ if (typeof target === 'string') return target;
139
+ }
140
+ return undefined;
141
+ }
129
142
  if (value !== null && typeof value === 'object') {
130
- for (const key of ['default', 'import', 'require']) {
131
- if (typeof value[key] === 'string') return value[key];
143
+ for (const key of ['default', 'import', 'require', 'node', 'module-sync']) {
144
+ const target = exportTarget(value[key]);
145
+ if (typeof target === 'string') return target;
132
146
  }
133
147
  }
134
148
  return undefined;
@@ -382,8 +396,17 @@ export function checkFilesList(manifest) {
382
396
  */
383
397
  /** The module the loader imports when it starts the bare package name. */
384
398
  export function rootEntry(manifest) {
385
- const root = typeof manifest.exports === 'object' && manifest.exports !== null ? manifest.exports['.'] : undefined;
386
- const entry = typeof root === 'string' ? root : manifest.main;
399
+ const exported = manifest.exports;
400
+ // A string `exports` is the root itself. A conditions object is only visible
401
+ // through `exports["."]`, and treating it as "no root" let a plugin whose
402
+ // root resolved to the CLI pass both doctor and verify.
403
+ const root =
404
+ typeof exported === 'string'
405
+ ? exported
406
+ : typeof exported === 'object' && exported !== null
407
+ ? exported['.']
408
+ : undefined;
409
+ const entry = exportTarget(root) ?? manifest.main;
387
410
  if (typeof entry !== 'string') return null;
388
411
  return entry.replace(/^\.\//, '');
389
412
  }
package/lib/release.mjs CHANGED
@@ -38,6 +38,44 @@ export function tagExists(dir, tag, run) {
38
38
  }
39
39
  }
40
40
 
41
+ /** The commit a tag names, or null when it cannot be resolved. */
42
+ export function tagCommit(dir, tag, run) {
43
+ const runGit = run ?? ((args) => git(dir, args));
44
+ try {
45
+ // `^{commit}` resolves an annotated tag to the commit it points at.
46
+ return runGit(['rev-parse', `refs/tags/${tag}^{commit}`]);
47
+ } catch {
48
+ try {
49
+ return runGit(['rev-parse', `refs/tags/${tag}`]);
50
+ } catch {
51
+ return null;
52
+ }
53
+ }
54
+ }
55
+
56
+ /** The current HEAD commit, or null when it cannot be resolved. */
57
+ export function headCommit(dir, run) {
58
+ const runGit = run ?? ((args) => git(dir, args));
59
+ try {
60
+ return runGit(['rev-parse', 'HEAD']);
61
+ } catch {
62
+ return null;
63
+ }
64
+ }
65
+
66
+ /**
67
+ * True when the tag exists and names the same commit as HEAD. A re-run after a
68
+ * failure has to be able to finish the release without moving the tag: the tag
69
+ * is what started the publish, so recreating it would be both unnecessary and
70
+ * wrong.
71
+ */
72
+ export function tagPointsAtHead(dir, tag, run) {
73
+ const runGit = run ?? ((args) => git(dir, args));
74
+ const head = headCommit(dir, runGit);
75
+ if (head === null) return false;
76
+ return tagCommit(dir, tag, runGit) === head;
77
+ }
78
+
41
79
  export function workingTreeIsClean(dir, run) {
42
80
  return (run ?? ((args) => git(dir, args)))(['status', '--porcelain']) === '';
43
81
  }
@@ -110,21 +148,41 @@ export async function release(options) {
110
148
  const version = report.manifest.version;
111
149
  const tag = tagName(version, tagPrefix);
112
150
 
113
- if (tagExists(dir, tag, gitRun) === true) {
114
- return { ok: false, stage: 'tag', failures: [{ check: 'tag', message: `${tag} already exists` }] };
115
- }
116
- if (workingTreeIsClean(dir, gitRun) === false) {
117
- const dirty = dirtyPaths(dir, 3, gitRun);
118
- const listed = dirty.length > 0 ? ` (${dirty.join(', ')})` : '';
151
+ const resuming = tagExists(dir, tag, gitRun) === true;
152
+ if (resuming === true && tagPointsAtHead(dir, tag, gitRun) === false) {
153
+ // A tag at another commit is not a resume: moving it would rewrite what the
154
+ // earlier release published. Name where it points, where HEAD is, and the
155
+ // 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);
158
+ const targetText = target ?? 'an unknown commit';
159
+ const headText = head ?? 'an unknown commit';
119
160
  return {
120
161
  ok: false,
121
- stage: 'git',
122
- failures: [{ check: 'git', message: `the working tree has uncommitted changes${listed}` }],
162
+ stage: 'tag',
163
+ failures: [{
164
+ check: 'tag',
165
+ message: `${tag} already exists and does not point at HEAD: tag ${tag} is at ${targetText}, HEAD is ${headText}. Delete the stale tag with \`git tag -d ${tag}\` and \`git push --delete origin ${tag}\`, then re-run release.`,
166
+ }],
123
167
  };
124
168
  }
169
+ if (resuming === false) {
170
+ // A resume does not create a tag, so the clean-tree rule that protects the
171
+ // tag does not apply: the index write from a previous attempt is allowed to
172
+ // be the only uncommitted change.
173
+ if (workingTreeIsClean(dir, gitRun) === false) {
174
+ const dirty = dirtyPaths(dir, 3, gitRun);
175
+ const listed = dirty.length > 0 ? ` (${dirty.join(', ')})` : '';
176
+ return {
177
+ ok: false,
178
+ stage: 'git',
179
+ failures: [{ check: 'git', message: `the working tree has uncommitted changes${listed}` }],
180
+ };
181
+ }
125
182
 
126
- gitRun(['tag', tag]);
127
- gitRun(['push', 'origin', tag]);
183
+ gitRun(['tag', tag]);
184
+ gitRun(['push', 'origin', tag]);
185
+ }
128
186
 
129
187
  // Not every plugin publishes from CI. `--publish` runs the publish here, so
130
188
  // the same command covers both kinds of repository.
package/lib/verify.mjs CHANGED
@@ -207,6 +207,10 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
207
207
  // and mounted nothing.
208
208
  const rootFile = rootEntry(report.manifest);
209
209
  let hostFace = null;
210
+ // A bundle that inserts a subpath plugin needs no root module, so there is
211
+ // nothing to import. The success line must not claim it imported a host half
212
+ // that was skipped.
213
+ let hostImported = false;
210
214
  if (rootFile !== null) {
211
215
  const absolute = path.join(installed, rootFile);
212
216
  if (fs.existsSync(absolute) === false) {
@@ -221,6 +225,7 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
221
225
  const { pathToFileURL } = await import('node:url');
222
226
  const loaded = await import(pathToFileURL(absolute).href);
223
227
  hostFace = loaded;
228
+ hostImported = true;
224
229
  if (typeof loaded.apply !== 'function') {
225
230
  return {
226
231
  ok: false,
@@ -261,7 +266,9 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
261
266
 
262
267
  // `--no-mount` skips the DOM, not the install: the host half is the half
263
268
  // that silently fails, and importing it needs nothing but Node.
264
- if (mount === false) return { ok: true, stage: 'pack', failures: [], files: packed.files, size: packed.size };
269
+ if (mount === false) {
270
+ return { ok: true, stage: 'pack', failures: [], files: packed.files, size: packed.size, hostImported };
271
+ }
265
272
 
266
273
  // Same convention the host uses: dsh.client.entry, then client.js.
267
274
  const entryFile = resolveEntry(installed, report.manifest);
@@ -304,7 +311,16 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
304
311
  installed,
305
312
  };
306
313
  }
307
- return { ok: true, stage: 'mount', failures: [], files: packed.files, size: packed.size, installed, text };
314
+ return {
315
+ ok: true,
316
+ stage: 'mount',
317
+ failures: [],
318
+ files: packed.files,
319
+ size: packed.size,
320
+ installed,
321
+ text,
322
+ hostImported,
323
+ };
308
324
  } catch (error) {
309
325
  return {
310
326
  ok: false,
@@ -316,5 +332,5 @@ async function inspectScratch({ dir, mount, report, packed, scratch }) {
316
332
  }
317
333
  }
318
334
 
319
- return { ok: true, stage: 'install', failures: [], files: packed.files, size: packed.size, installed };
335
+ return { ok: true, stage: 'install', failures: [], files: packed.files, size: packed.size, installed, hostImported };
320
336
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.7",
3
+ "version": "0.20.9",
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": {