dsh-plugin-toolkit 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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`:
+
+- The index entry came out with `publishTimestamp: null`. The registry was asked for the abbreviated packument (`application/vnd.npm.install-v1+json`), which has no `time` field at all — so the tool could see the version and still have no publish date. It now asks for the full document, and waits for `time[version]` before writing the entry.
+- `git rev-parse` on a tag that does not exist yet printed `fatal: ambiguous argument …` in the middle of a successful release; stderr is now dropped for that call.
+- "the working tree has uncommitted changes" now names up to three paths.
+- A folder without `package.json` raised a stack trace instead of returning a preflight failure.
+
 ## 0.3.4
 
 - CI now runs on Windows as well as Linux and macOS; two tests assumed a POSIX temp path (`/tmp/…`) and were rewritten with `path.join`.

package/README.md

@@ -166,10 +166,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.
 
-Steps that touch your repository are printed, never guessed at. `--dry-run` prints the whole sequence with the commands it would run.
+```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
+```
+
+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

@@ -11,8 +11,12 @@ export const REGISTRY = 'https://registry.npmjs.org';
 export async function packument(name, options = {}) {
   const base = options.registry ?? REGISTRY;
   const request = options.fetch ?? fetch;
+  // The full document, not the abbreviated install one: the index entry needs
+  // `time[version]`, and `application/vnd.npm.install-v1+json` omits `time`
+  // entirely — which is why an abbreviated fetch can see a version and still
+  // have no publish date to write.
   const response = await request(`${base}/${name.replace('/', '%2F')}`, {
-    headers: { accept: 'application/vnd.npm.install-v1+json' },
+    headers: { accept: 'application/json' },
   });
   if (response.status === 404) return null;
   if (response.ok === false) {
@@ -40,6 +44,12 @@ export function hasVersion(document, version) {
  * `onWait` is called after each miss so the CLI can report progress.
  */
 export async function waitForVersion(name, version, options = {}) {
+  // `requireTime` matters for the market index: `versions` can list a version
+  // before the registry has written its `time` entry, and an index entry with a
+  // null timestamp is rejected by the checker.
+  const ready = options.requireTime === true
+    ? (document) => hasVersion(document, version) === true && publishedAt(document, version) !== null
+    : (document) => hasVersion(document, version) === true;
   const budgetMs = options.budgetMs ?? 8 * 60 * 1000;
   const intervalMs = options.intervalMs ?? 10 * 1000;
   const now = options.now ?? Date.now;
@@ -50,7 +60,12 @@ export async function waitForVersion(name, version, options = {}) {
   for (;;) {
     attempts += 1;
     const document = await packument(name, options);
-    if (hasVersion(document, version) === true) {
+    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 };
     }
     if (now() - started >= budgetMs) {

package/lib/release.mjs

@@ -12,26 +12,38 @@ 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) {
-  return execFileSync('git', args, { cwd: dir, encoding: 'utf8' }).trim();
+  // 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', '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, 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);
 }
 
 /**
@@ -69,7 +81,16 @@ export async function release(options) {
     onChange,
   } = options;
 
-  const report = doctor(dir);
+  const gitRun = options.git ?? ((args) => git(dir, args));
+
+  let report;
+  try {
+    report = doctor(dir);
+  } catch (error) {
+    // A folder without package.json is a preflight failure, not a crash: the
+    // command's job is to say what is wrong, and a stack trace is not an answer.
+    return { ok: false, stage: 'preflight', failures: [{ check: 'manifest', message: error.message }] };
+  }
   if (report.failures.length > 0) {
     return { ok: false, stage: 'preflight', failures: report.failures };
   }
@@ -78,21 +99,28 @@ 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) {
+  if (workingTreeIsClean(dir, gitRun) === false) {
+    const dirty = dirtyPaths(dir, 3, gitRun);
+    const listed = dirty.length > 0 ? ` (${dirty.join(', ')})` : '';
     return {
       ok: false,
       stage: 'git',
-      failures: [{ check: 'git', message: 'the working tree has uncommitted changes' }],
+      failures: [{ check: 'git', message: `the working tree has uncommitted changes${listed}` }],
     };
   }
 
-  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,
@@ -100,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,
@@ -118,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,
@@ -134,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.4",
+  "version": "0.4.0",
   "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": {