dsh-plugin-toolkit 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.8.5
+
+- `release --market <dir>`: write the index entry into a checkout of the
+  repository that owns the index, and open the pull request there. Before this,
+  `release` only touched a `market/index.json` inside the plugin's own repo, so
+  anyone listed in a central market had to patch the entry by hand — which is
+  where the timestamp goes wrong.
+- `--index` still names the file inside that repository.
+
+## 0.8.4
+
+- README: `## When the panel does not appear` — the five checks that explain a
+  successful install with nothing on screen (restart, root export, tarball,
+  patch row, a bundle that throws). Each one is a failure this tool has already
+  hit. A test keeps the section from losing a step.
+- `doctor` table lists the new `root export` check; the verify example no longer
+  pins an old version in its own docs.
+
 ## 0.8.3
 
 `verify` now imports the host half it just installed.

package/README.md

@@ -247,6 +247,7 @@ latest release.
 | `patch file` | The path declared above must be a real file |
 | `client entry` | If `dsh.client` is declared, the bundle has to be there |
 | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` |
+| `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 |
 
 Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged.
 
@@ -255,7 +256,7 @@ Exit code is `0` when the plugin can be installed and `1` when it cannot, so it
 `doctor` reads your working copy. Users install the tarball, and a `files` list can ship everything except the panel — `doctor` will not notice.
 
 ```sh
-$ npx dsh-plugin-toolkit@0.7.0 verify .
+$ npx dsh-plugin-toolkit verify .
 ok  packed 5 file(s), installed the tarball, mounted the panel
     My panel This panel came from dsh-plugin init. Clicks: 0
 ```
@@ -263,11 +264,37 @@ ok  packed 5 file(s), installed the tarball, mounted the panel
 It packs, installs that tarball into a throwaway directory, then mounts the bundle **from the installed copy**. When the `files` list drops the panel:
 
 ```sh
-$ npx dsh-plugin-toolkit@0.7.0 verify .
+$ npx dsh-plugin-toolkit verify .
 dsh-plugin verify: stopped at pack
   ✗ pack: the tarball does not contain client.js, so the installed plugin has no panel
 ```
 
+## When the panel does not appear
+
+The install reports success and nothing shows up. In this order:
+
+1. **Did the host restart?** Client bundles are read at startup. `dsh plugin add`
+   writes the profile; the running window still has the old bundle.
+2. **Is the root export the plugin?**
+   ```sh
+   node -e "import('my-plugin').then((m) => console.log(typeof m.apply))"
+   ```
+   `function` is what the loader needs. `undefined` means `exports["."]` points
+   at the CLI — `0.8.0` of this tool shipped exactly that.
+3. **Does the tarball ship the panel?** `dsh-plugin verify .` installs what users
+   get and mounts it. `doctor` cannot see this.
+4. **Is the patch row shaped right?** `cordis.patch.yml` needs one `- insert:`
+   entry with `id` and `name`:
+   ```yaml
+   - insert:
+       - id: my-plugin
+         name: my-plugin
+         config: {}
+   ```
+5. **Did the client bundle throw?** The host logs the loader error with the
+   plugin id; a bundle that throws at factory time looks identical to one that
+   never loaded.
+
 ## What `release` does
 
 `release` runs the sequence in the order that fails cheapest first:
@@ -293,6 +320,19 @@ merged
 
 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.
 
+### When the index lives in someone else's repository
+
+Most plugins are listed in a central market repository, not their own. Point
+`--market` at a checkout of that repository and the entry — and the pull
+request — land there:
+
+```sh
+$ dsh-plugin release . --market ../market-repo --pr --merge
+tagged plugin-v0.4.0, npm served my-plugin@0.4.0 after 92s
+updated /Users/me/market-repo/market/index.json on market/0.4.0
+merged
+```
+
 ## Exit codes
 
 | Code | Meaning |

package/lib/cli.mjs

@@ -37,6 +37,7 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
 Flags
   --dry-run                 show the steps without touching anything
   --index <path>            index file, default market/index.json
+  --market <dir>            with release: a checkout of the repository that holds the index
   --tag-prefix <prefix>     default plugin-v
   --budget <seconds>        how long to wait for npm, default 480
   --pr                      commit the index on a branch, push it, open the pull request
@@ -72,6 +73,7 @@ function flags(argv) {
     else if (token === '--pr') parsed.pr = true;
     else if (token === '--merge') parsed.merge = true;
     else if (token === '--base') parsed.base = argv[++index];
+    else if (token === '--market') parsed.market = argv[++index];
     else if (token.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
     else parsed.positional.push(token);
   }
@@ -210,6 +212,7 @@ export async function run(argv, io = console) {
     const result = await release({
       dir,
       indexFile: options.index,
+      marketDir: options.market,
       tagPrefix: options.tagPrefix,
       budgetMs: options.budget === undefined ? undefined : options.budget * 1000,
       pr: options.pr === true,

package/lib/release.mjs

@@ -51,7 +51,7 @@ export function dirtyPaths(dir, limit = 3, run) {
  * anything runs is what makes `--dry-run` useful: it shows the whole sequence
  * and the exact commands.
  */
-export function plan({ dir = process.cwd(), version, name, tagPrefix = 'plugin-v', indexFile = 'market/index.json' }) {
+export function plan({ dir = process.cwd(), version, name, tagPrefix = 'plugin-v', indexFile = 'market/index.json', marketDir }) {
   const report = doctor(dir);
   const resolvedName = name ?? report.manifest.name ?? 'this-plugin';
   const resolvedVersion = version ?? report.manifest.version ?? '0.0.0';
@@ -61,7 +61,13 @@ export function plan({ dir = process.cwd(), version, name, tagPrefix = 'plugin-v
     { title: `Create the tag ${tag}`, command: `git tag ${tag}`, runs: true },
     { title: 'Push the tag, which starts the release workflow', command: `git push origin ${tag}`, runs: true },
     { title: `Wait until the registry serves ${resolvedName}@${resolvedVersion}`, command: `GET /${resolvedName}`, runs: true },
-    { title: 'Write the version into the market index, with the publish time the registry reported', command: `patch ${indexFile}`, runs: true },
+    {
+      title: marketDir === undefined
+        ? 'Write the version into the market index, with the publish time the registry reported'
+        : `Write the version into the market index at ${marketDir}`,
+      command: `patch ${path.join(marketDir ?? '', indexFile)}`,
+      runs: true,
+    },
     { title: 'Open the index pull request', command: 'gh pr create', runs: false },
     { title: 'Re-read the live index and confirm the version is listed', command: 'GET market/index.json', runs: false },
   ];
@@ -74,6 +80,7 @@ export async function release(options) {
     registry,
     tagPrefix = 'plugin-v',
     indexFile = 'market/index.json',
+    marketDir,
     budgetMs,
     intervalMs,
     sleep,
@@ -155,7 +162,10 @@ export async function release(options) {
 
   const timestamp = publishedAt(waited.document, version);
   const entry = buildEntry({ version, publishTimestamp: timestamp, hostRange: report.notes.hostRange });
-  const indexPath = path.join(dir, indexFile);
+  // Most plugins are listed in someone else's index: `--market` points at a
+  // checkout of that repository, and the entry plus the pull request land there.
+  const indexRoot = typeof marketDir === 'string' && marketDir.length > 0 ? path.resolve(marketDir) : dir;
+  const indexPath = path.join(indexRoot, indexFile);
   let indexUpdate = null;
   if (fs.existsSync(indexPath) === true) {
     try {
@@ -163,10 +173,10 @@ export async function release(options) {
       const after = addVersion(before, name, entry);
       if (after !== before) {
         writeIndex(indexPath, after);
-        indexUpdate = { file: indexFile, version, entry };
+        indexUpdate = { file: indexPath, version, entry };
         if (typeof onChange === 'function') onChange(indexUpdate);
       } else {
-        indexUpdate = { file: indexFile, version, entry, unchanged: true };
+        indexUpdate = { file: indexPath, version, entry, unchanged: true };
       }
     } catch (error) {
       return { ok: false, stage: 'index', failures: [{ check: 'index', message: error.message }] };
@@ -188,16 +198,17 @@ export async function release(options) {
   // The index change is one line, but it still needs a branch, a pull request,
   // a green CI and a merge; doing that by hand is where "forgot to open the PR"
   // happens.
-  const ghRunner = options.gh ?? defaultGh(dir);
+  const ghRunner = options.gh ?? defaultGh(indexRoot);
+  const marketGit = options.marketGit ?? (indexRoot === dir ? options.git : ((args) => git(indexRoot, args)));
   const pull = await openIndexPr({
-    dir,
+    dir: indexRoot,
+    git: marketGit,
     indexFile,
     version,
     base: options.base ?? 'main',
     branch: options.branch,
     title: options.prTitle,
     body: options.prBody,
-    git: options.git,
     gh: ghRunner,
     onStep: options.onStep,
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
   "type": "module",
   "bin": {