dsh-plugin-toolkit 0.3.5 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.1
+
+- `examples/`: four runnable files (`mount-a-bundle`, `route-stubs`, `baseline`, `aria`), each showing one thing testkit does.
+- `test/examples.test.mjs` runs every example and asserts it prints exactly what the README shows, and that the README names each one. An example that does not run teaches a shape that no longer exists.
+- `fixtures/fetching-bundle/`: a bundle that calls its host on mount, so the route-stub example asserts something real instead of printing zeros.
+
+## 0.4.0
+
+`release` can now finish the job instead of printing the next command.
+
+- `--pr` commits the index on `market/<version>`, pushes it, and opens the pull request with `gh`.
+- `--merge` (with `--pr`) waits for `gh pr checks` to settle and squash-merges.
+- A repository with no CI is treated as settled rather than waited on; `gh` prints "no checks reported" on **stderr** and exits 1, which is why stderr is now piped instead of dropped.
+- Re-running a release after a failure no longer throws: the same version with the same publish time is a no-op, and a different timestamp stops with both values in the message.
+- A package the registry has never heard of fails immediately (`the registry has no package named …`) instead of polling for eight minutes.
+- `release` forwards `fetch`, so a caller can answer instead of npm.
+
+Verified end to end against a throwaway package: tag → publish → registry wait → index write → PR #3 → checks → merged.
+
 ## 0.3.5
 
 Four bugs found by running `release` for real against a throwaway package, instead of only `--dry-run`:

package/README.md

@@ -78,6 +78,27 @@ assert.match(panel.must('[role="status"]').textContent, /Score moved 71 → 77/)
 
 `must()` throws with the rendered markup when the selector misses, which is the difference between "the assertion failed" and "here is what the user actually got".
 
+Every example below is a file in this repository, run by CI, and the output shown is the output it prints:
+
+| Example | What it shows |
+| --- | --- |
+| `node examples/mount-a-bundle.mjs` | mount a real bundle, read the text, click, read it again |
+| `node examples/route-stubs.mjs` | answer the routes a panel asks for, and assert on the requests |
+| `node examples/baseline.mjs` | a DOM baseline compared on every run |
+| `node examples/aria.mjs` | what assistive tech sees |
+
+```sh
+$ node examples/mount-a-bundle.mjs
+Demo panel Count 0 0
+Demo panel Count 1 1
+```
+
+```sh
+$ node examples/route-stubs.mjs
+Score 71
+asked for: 1 route(s), undeclared route answers 404
+```
+
 To look at a bundle by hand:
 
 ```sh
@@ -166,10 +187,22 @@ Exit code is `0` when the plugin can be installed and `1` when it cannot, so it
 2. Refuse to run on a dirty tree, or if the tag already exists.
 3. Create and push the tag, which starts the plugin's release workflow.
 4. Poll the registry until it actually serves that version, reporting each wait.
-5. Write the index entry with the publish time **the registry reports**, not the local clock.
-6. Print the exact `git add` / `gh pr create` commands for the index change.
+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.
+6. With `--pr`: commit that entry on `market/<version>`, push it, and open the pull request. With `--merge` as well: wait for `gh pr checks` to settle, then squash-merge.
+
+```sh
+npx dsh-plugin release . --pr --merge
+```
+
+```
+tagged plugin-v0.4.0, npm served my-plugin@0.4.0 after 82s
+updated market/index.json on market/0.4.0
+opened https://github.com/me/my-plugin/pull/3
+checks settled after 1s (1 look(s))
+merged
+```
 
-Steps that touch your repository are printed, never guessed at. `--dry-run` prints the whole sequence with the commands it would run.
+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.
 
 ## Exit codes
 

package/lib/cli.mjs

@@ -12,7 +12,7 @@ import { auditVersions, readIndex } from './index-file.mjs';
 export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugins
 
   dsh-plugin doctor [dir]            check the manifest, README and bundle
-  dsh-plugin release [dir] [flags]   tag, wait for npm, update the market index
+  dsh-plugin release [dir] [flags]   tag, wait for npm, update the market index, open the PR
   dsh-plugin index [dir]             audit every version in market/index.json
   dsh-plugin mount <client.js>       render a client bundle in Node and print what a user would see
   dsh-plugin dev [dir] [flags]       copy a rebuilt bundle into the installed plugin and confirm the reload
@@ -22,6 +22,9 @@ Flags
   --index <path>            index file, default market/index.json
   --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
+  --merge                   with --pr: wait for checks, then squash-merge
+  --base <branch>           base branch for the pull request, default main
 `;
 
 function flags(argv) {
@@ -42,6 +45,9 @@ function flags(argv) {
     else if (token === '--once') parsed.once = true;
     else if (token === '--debounce') parsed.debounce = Number(argv[++index]);
     else if (token === '--timeout') parsed.timeout = Number(argv[++index]);
+    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.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
     else parsed.positional.push(token);
   }
@@ -152,6 +158,10 @@ export async function run(argv, io = console) {
       indexFile: options.index,
       tagPrefix: options.tagPrefix,
       budgetMs: options.budget === undefined ? undefined : options.budget * 1000,
+      pr: options.pr === true,
+      merge: options.merge === true,
+      base: options.base,
+      onStep: (name) => io.log(`  → ${name}`),
       onWait: ({ attempts, waitedMs }) => {
         io.log(`  … ${name}@${version} not on the registry yet (${attempts} checks, ${Math.round(waitedMs / 1000)}s)`);
       },
@@ -164,12 +174,30 @@ export async function run(argv, io = console) {
     }
 
     io.log(`tagged ${result.tag}, npm served ${name}@${version} after ${Math.round(result.waitedMs / 1000)}s`);
-    if (result.indexUpdate !== null) {
+    if (result.indexUpdate !== null && result.indexUpdate.unchanged === true) {
+      io.log(`${result.indexUpdate.file} already carried ${version}; nothing to commit`);
+    } else if (result.indexUpdate !== null && result.pullRequest === undefined) {
       io.log(`updated ${result.indexUpdate.file} — commit it and open the PR:`);
       io.log(`  git add ${result.indexUpdate.file} && git commit -m "market: ${version}" && gh pr create --fill`);
+    } else if (result.indexUpdate !== null) {
+      io.log(`updated ${result.indexUpdate.file} on ${result.pullRequest.branch}`);
     } else {
       io.log('no market/index.json here, so only the tag and the publish happened');
     }
+
+    if (result.pullRequest !== undefined) {
+      if (result.pullRequest.ok !== true) {
+        io.error(`the pull request was not opened (${result.pullRequest.stage})`);
+        return 1;
+      }
+      io.log(`opened ${result.pullRequest.url}`);
+    }
+    if (result.checks !== undefined) {
+      io.log(`checks settled after ${Math.round(result.checks.waitedMs / 1000)}s (${result.checks.attempts} look(s))`);
+    }
+    if (result.merged !== undefined && result.merged.ok === true) {
+      io.log('merged');
+    }
     return 0;
   }
 

package/lib/index-file.mjs

@@ -34,8 +34,15 @@ export function addVersion(index, name, entry) {
     throw new Error(`the index has no plugin called "${name}"`);
   }
   const versions = Array.isArray(plugin.versions) ? plugin.versions : [];
-  if (versions.some((existing) => existing.version === entry.version)) {
-    throw new Error(`${name}@${entry.version} is already in the index`);
+  const existing = versions.find((candidate) => candidate.version === entry.version);
+  if (existing !== undefined) {
+    // Re-running a release after a failure is normal, so the same version with
+    // the same publish time is a no-op; a different timestamp means the index
+    // and the registry disagree, and that is worth stopping for.
+    if (existing.publishTimestamp === entry.publishTimestamp) return index;
+    throw new Error(
+      `${name}@${entry.version} is already in the index with publishTimestamp ${existing.publishTimestamp}, not ${entry.publishTimestamp}`,
+    );
   }
   return {
     ...index,

package/lib/pr.mjs

@@ -0,0 +1,144 @@
+/**
+ * The last mile of a release: the index change is one line, but it still needs a
+ * branch, a pull request, a green CI, and a merge.
+ *
+ * Every side effect goes through an injected runner, so the sequence can be
+ * asserted without a network, a repository, or a `gh` login.
+ */
+import { execFileSync } from 'node:child_process';
+
+// stderr is piped, not inherited: git's "fatal: ambiguous argument" for a tag
+// that does not exist yet and gh's "no checks reported" both arrive there, and
+// both are expected misses that must not read as failures — but they still have
+// to be readable by the caller.
+export function defaultGit(dir) {
+  return (args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+export function defaultGh(dir) {
+  return (args) => execFileSync('gh', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+export function branchName(version, prefix = 'market/') {
+  return `${prefix}${version}`;
+}
+
+/**
+ * Commit the index on its own branch, push it, and open the pull request.
+ * Returns `{ok, branch, url}` or `{ok:false, stage, reason}`.
+ */
+export async function openIndexPr(options) {
+  const {
+    dir,
+    indexFile,
+    version,
+    base = 'main',
+    branch = branchName(version),
+    git = defaultGit(dir),
+    gh = defaultGh(dir),
+    title,
+    body,
+    onStep,
+  } = options;
+  const step = (name) => {
+    if (typeof onStep === 'function') onStep(name);
+  };
+
+  try {
+    step('branch');
+    git(['checkout', '-b', branch]);
+  } catch {
+    // An existing branch means a previous run got this far; reuse it rather than
+    // failing on the one step that is safe to repeat.
+    try {
+      git(['checkout', branch]);
+    } catch (error) {
+      return { ok: false, stage: 'branch', reason: `could not create or check out ${branch}: ${error.message}` };
+    }
+  }
+
+  try {
+    step('commit');
+    git(['add', indexFile]);
+    git(['commit', '-m', `market: ${version}`]);
+  } catch (error) {
+    return { ok: false, stage: 'commit', reason: error.message };
+  }
+
+  try {
+    step('push');
+    git(['push', '-u', 'origin', branch]);
+  } catch (error) {
+    return { ok: false, stage: 'push', reason: error.message };
+  }
+
+  try {
+    step('pr');
+    const url = gh([
+      'pr',
+      'create',
+      '--base',
+      base,
+      '--head',
+      branch,
+      '--title',
+      title ?? `market: ${version}`,
+      '--body',
+      body ?? `Adds ${version} to the market index, with the publish time the registry reported.`,
+    ]);
+    return { ok: true, branch, url: url.split('\n').pop() ?? url };
+  } catch (error) {
+    return { ok: false, stage: 'pr', reason: error.message };
+  }
+}
+
+/** Poll `gh pr checks` until every check has settled. */
+export async function waitForChecks(options) {
+  const {
+    url,
+    gh,
+    budgetMs = 30 * 60 * 1000,
+    intervalMs = 20 * 1000,
+    now = Date.now,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    onWait,
+  } = options;
+  const started = now();
+  let attempts = 0;
+  for (;;) {
+    attempts += 1;
+    let output = '';
+    try {
+      output = gh(['pr', 'checks', url, '--json', 'state', '--jq', '.[].state']);
+    } catch (error) {
+      // `gh pr checks` exits non-zero while checks are still pending, and also
+      // when the repository has no CI at all — the second case is not a wait.
+      output = String(error.stdout ?? '');
+      // `gh` writes "no checks reported on the 'x' branch" to stdout and exits 1.
+      const message = `${error.message ?? ''}${error.stdout ?? ''}${error.stderr ?? ''}`;
+      if (/no checks reported/i.test(message) === true) {
+        return { ok: true, attempts, waitedMs: now() - started, states: [], noChecks: true };
+      }
+    }
+    const states = output.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    const pending = states.filter((state) => ['PENDING', 'QUEUED', 'IN_PROGRESS', ''].includes(state));
+    const failed = states.filter((state) => ['FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED'].includes(state));
+    if (failed.length > 0) return { ok: false, attempts, waitedMs: now() - started, states, reason: `${failed.length} check(s) failed` };
+    if (states.length > 0 && pending.length === 0) return { ok: true, attempts, waitedMs: now() - started, states };
+    if (now() - started >= budgetMs) {
+      return { ok: false, attempts, waitedMs: now() - started, states, timedOut: true, reason: 'checks did not settle in time' };
+    }
+    if (typeof onWait === 'function') onWait({ attempts, waitedMs: now() - started, states });
+    await sleep(intervalMs);
+  }
+}
+
+export async function mergePr(options) {
+  const { url, gh, method = 'squash' } = options;
+  try {
+    gh(['pr', 'merge', url, `--${method}`]);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: error.message };
+  }
+}

package/lib/registry.mjs

@@ -60,6 +60,11 @@ export async function waitForVersion(name, version, options = {}) {
   for (;;) {
     attempts += 1;
     const document = await packument(name, options);
+    if (document === null && options.requirePackage !== false) {
+      // A package that does not exist will not appear by waiting: say so now
+      // instead of polling for eight minutes.
+      return { document, attempts, waitedMs: now() - started, missingPackage: true };
+    }
     if (ready(document) === true) {
       return { document, attempts, waitedMs: now() - started };
     }

package/lib/release.mjs

@@ -12,34 +12,35 @@ import path from 'node:path';
 import { doctor } from './doctor.mjs';
 import { addVersion, buildEntry, readIndex, writeIndex } from './index-file.mjs';
 import { publishedAt, waitForVersion } from './registry.mjs';
+import { defaultGh, mergePr, openIndexPr, waitForChecks } from './pr.mjs';
 
 function git(dir, args) {
   // stderr is dropped on purpose: `rev-parse` on a tag that does not exist yet is
   // an expected miss, and git prints "fatal: ambiguous argument" for it, which
   // reads like a failure in the middle of a successful release.
-  return execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  return execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
 export function tagName(version, prefix = 'plugin-v') {
   return `${prefix}${version}`;
 }
 
-export function tagExists(dir, tag) {
+export function tagExists(dir, tag, run) {
   try {
-    git(dir, ['rev-parse', `refs/tags/${tag}`]);
+    (run ?? ((args) => git(dir, args)))(['rev-parse', `refs/tags/${tag}`]);
     return true;
   } catch {
     return false;
   }
 }
 
-export function workingTreeIsClean(dir) {
-  return git(dir, ['status', '--porcelain']) === '';
+export function workingTreeIsClean(dir, run) {
+  return (run ?? ((args) => git(dir, args)))(['status', '--porcelain']) === '';
 }
 
 /** The paths git would carry into the tag, so the message can name them. */
-export function dirtyPaths(dir, limit = 3) {
-  const status = git(dir, ['status', '--porcelain']);
+export function dirtyPaths(dir, limit = 3, run) {
+  const status = (run ?? ((args) => git(dir, args)))(['status', '--porcelain']);
   if (status === '') return [];
   const paths = status.split('\n').map((line) => line.slice(3).trim()).filter((line) => line !== '');
   return paths.slice(0, limit);
@@ -80,6 +81,8 @@ export async function release(options) {
     onChange,
   } = options;
 
+  const gitRun = options.git ?? ((args) => git(dir, args));
+
   let report;
   try {
     report = doctor(dir);
@@ -96,11 +99,11 @@ export async function release(options) {
   const version = report.manifest.version;
   const tag = tagName(version, tagPrefix);
 
-  if (tagExists(dir, tag) === true) {
+  if (tagExists(dir, tag, gitRun) === true) {
     return { ok: false, stage: 'tag', failures: [{ check: 'tag', message: `${tag} already exists` }] };
   }
-  if (workingTreeIsClean(dir) === false) {
-    const dirty = dirtyPaths(dir);
+  if (workingTreeIsClean(dir, gitRun) === false) {
+    const dirty = dirtyPaths(dir, 3, gitRun);
     const listed = dirty.length > 0 ? ` (${dirty.join(', ')})` : '';
     return {
       ok: false,
@@ -109,13 +112,15 @@ export async function release(options) {
     };
   }
 
-  git(dir, ['tag', tag]);
-  git(dir, ['push', 'origin', tag]);
+  gitRun(['tag', tag]);
+  gitRun(['push', 'origin', tag]);
 
   const waited = await waitForVersion(name, version, {
     // Wait for the publish *time* as well: `versions` can appear a moment before
     // `time`, and an index entry with a null timestamp fails the market checker.
     requireTime: true,
+    // Forwarded so a caller (and the tests) can answer instead of npm.
+    fetch: options.fetch,
     registry,
     budgetMs,
     intervalMs,
@@ -123,6 +128,18 @@ export async function release(options) {
     now,
     onWait: options.onWait,
   });
+  if (waited.missingPackage === true) {
+    return {
+      ok: false,
+      stage: 'registry',
+      failures: [
+        {
+          check: 'registry',
+          message: `the registry has no package named ${name} (tag ${tag} is pushed; publish it, then re-run)`,
+        },
+      ],
+    };
+  }
   if (waited.timedOut === true) {
     return {
       ok: false,
@@ -141,14 +158,22 @@ export async function release(options) {
   const indexPath = path.join(dir, indexFile);
   let indexUpdate = null;
   if (fs.existsSync(indexPath) === true) {
-    const before = readIndex(indexPath);
-    const after = addVersion(before, name, entry);
-    writeIndex(indexPath, after);
-    indexUpdate = { file: indexFile, version, entry };
-    if (typeof onChange === 'function') onChange(indexUpdate);
+    try {
+      const before = readIndex(indexPath);
+      const after = addVersion(before, name, entry);
+      if (after !== before) {
+        writeIndex(indexPath, after);
+        indexUpdate = { file: indexFile, version, entry };
+        if (typeof onChange === 'function') onChange(indexUpdate);
+      } else {
+        indexUpdate = { file: indexFile, version, entry, unchanged: true };
+      }
+    } catch (error) {
+      return { ok: false, stage: 'index', failures: [{ check: 'index', message: error.message }] };
+    }
   }
 
-  return {
+  const result = {
     ok: true,
     stage: 'index',
     tag,
@@ -157,4 +182,50 @@ export async function release(options) {
     waitedMs: waited.waitedMs,
     indexUpdate,
   };
+
+  if (options.pr !== true || indexUpdate === null) return result;
+
+  // 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 pull = await openIndexPr({
+    dir,
+    indexFile,
+    version,
+    base: options.base ?? 'main',
+    branch: options.branch,
+    title: options.prTitle,
+    body: options.prBody,
+    git: options.git,
+    gh: ghRunner,
+    onStep: options.onStep,
+  });
+  result.pullRequest = pull;
+  if (pull.ok !== true) {
+    return { ...result, ok: false, stage: `pr:${pull.stage}`, failures: [{ check: 'pr', message: pull.reason }] };
+  }
+
+  if (options.merge !== true) return result;
+
+  const checks = await waitForChecks({
+    url: pull.url,
+    gh: ghRunner,
+    budgetMs: options.checksBudgetMs,
+    intervalMs: options.checksIntervalMs,
+    sleep: options.sleep,
+    now: options.now,
+    onWait: options.onChecks,
+  });
+  result.checks = checks;
+  if (checks.ok !== true) {
+    return { ...result, ok: false, stage: 'checks', failures: [{ check: 'checks', message: checks.reason }] };
+  }
+
+  const merged = await mergePr({ url: pull.url, gh: ghRunner, method: options.mergeMethod });
+  result.merged = merged;
+  if (merged.ok !== true) {
+    return { ...result, ok: false, stage: 'merge', failures: [{ check: 'merge', message: merged.reason }] };
+  }
+  return { ...result, stage: 'merged' };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "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": {