@jrpool/kilotest 59.1.3 → 59.1.4

package/docs/AI-TOOLS.md

@@ -29,7 +29,7 @@ The internal features that make Kilotest a collection of tools for language mode
 - A `server.json` file, conforming to the [MCP server schema](https://modelcontextprotocol.io/), and a GitHub Actions workflow (`publish-mcp.yml`) that authenticates via GitHub OIDC and publishes that file to the official MCP Registry whenever `server.json` or `api/version.ts` changes on the `main` branch.
 - A `capability.md` file with a URL, summarizing what Kilotest tools can do.
 - `mcp`, `mcp-server`, and `modelcontextprotocol` keywords in `package.json`, supporting discovery of the `@jrpool/kilotest` npm package by tools and humans searching the npm registry for MCP servers.
-- An `lhm.plugin.json` file, conforming to the [LobeHub plugin manifest format](https://market.lobehub.com/s/publish-mcp/references/manifest), declaring Kilotest as a plugin in the [LobeHub MCP Market](https://lobehub.com/mcp). Publishing and updating are non-automated (`lhm plugin publish`/`update`), because LobeHub requires browser-based OAuth and does not support machine-to-machine publishing.
+- An `lhm.plugin.json` file, conforming to the [LobeHub plugin manifest format](https://market.lobehub.com/s/publish-mcp/references/manifest), declaring Kilotest as a plugin in the [LobeHub MCP Market](https://lobehub.com/mcp). Publishing and updating are non-automated (`lhm plugin publish` for the initial listing; thereafter `npm run publish:lhm`, which wraps `lhm plugin update` and also runs from the `postpublish` hook), because LobeHub requires browser-based OAuth and does not support machine-to-machine publishing.
 - A `sitemap.xml` file.
 - Documentation in the `README.md` file.
 - This `AI-TOOLS.md` file.
@@ -62,11 +62,11 @@ The external features that support the use of Kilotest as a collection of AI too
 
 ## Required maintenance
 
-Whenever the `version` property of the `package.json` file is updated:
+Releasing a new version is a two-script procedure:
 
-- Update `openapi.yaml` and the versions of `server.json` and `lhm.plugin.json` (`npm run generate`).
-- Create a pull request and merge to `main` (triggers `publish-mcp.yml` automatically for the MCP Registry).
-- Execute `lhm plugin update --dir .` (for LobeHub).
+- On a feature branch, commit all substantive changes, then execute `npm run prePR -- <level>` (`major`, `minor`, or `patch`). The script bumps `package.json` and `package-lock.json`, regenerates `openapi.yaml` and the versions of `server.json` and `lhm.plugin.json` via the `version` hook, commits and pushes the result, and records the branch name for the next step.
+- Submit a pull request and merge it to `main` (triggers `publish-mcp.yml` automatically for the MCP Registry).
+- Execute `npm run postPR`. The script checks out and pulls `main`, verifies that the merge landed, publishes to npm (whose `postpublish` hook updates the LobeHub listing), deletes the feature branch, and prunes remote-tracking branches. If the LobeHub update fails, retry it alone with `npm run publish:lhm`.
 
 ## Use cases
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "59.1.3",
+  "version": "59.1.4",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",
@@ -14,7 +14,13 @@
     "test": "c8 node --require ./test/setup.ts --experimental-test-module-mocks --test --test-concurrency=1 --test-randomize '**/*.test.ts'",
     "test:smoke": "node smokeTest.ts",
     "checkinfo": "node checkinfo.ts",
-    "generate": "node scripts/generate-openapi.ts && node scripts/update-versions.ts"
+    "generate": "node scripts/generate-openapi.ts && node scripts/update-versions.ts",
+    "version": "npm run generate",
+    "prepublishOnly": "test \"$(git branch --show-current)\" = main",
+    "postpublish": "npm run publish:lhm",
+    "publish:lhm": "npx -y @lobehub/market-cli plugin update --dir .",
+    "prePR": "node scripts/prePR.ts",
+    "postPR": "node scripts/postPR.ts"
   },
   "repository": {
     "type": "git",

package/scripts/postPR.ts

@@ -0,0 +1,89 @@
+/*
+  postPR.ts
+  Finalizes a release after the prePR pull request has been merged: checks out main, pulls, verifies that the merge landed, publishes to npm (the "postpublish" hook then updates the LobeHub listing), deletes the feature branch, and prunes remote-tracking branches. The feature-branch name is read from the marker file written by prePR.ts, or from an optional command-line argument.
+*/
+
+// IMPORTS
+
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// CONSTANTS
+
+const markerFile = 'kilotest-pr-branch';
+
+// FUNCTIONS
+
+// Runs a command with inherited stdio and throws on failure.
+const run = (command: string, args: string[]): void => {
+  if (spawnSync(command, args, {stdio: 'inherit'}).status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+};
+// Runs a command and returns its trimmed standard output.
+const capture = (command: string, args: string[]): string => {
+  const result = spawnSync(command, args, {encoding: 'utf8'});
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+  return result.stdout.trim();
+};
+// Returns the absolute path of a file inside the git directory.
+const gitPath = (name: string): string =>
+  path.join(capture('git', ['rev-parse', '--absolute-git-dir']), name);
+// Exits unless the working tree is clean.
+const requireCleanTree = (): void => {
+  const dirty = capture('git', ['status', '--porcelain']);
+  if (dirty) {
+    console.error(`Working tree is not clean. Commit or stash all changes first:\n${dirty}`);
+    process.exit(1);
+  }
+};
+// Returns the version field of package.json, either from the working tree or from a git ref.
+const versionOf = (ref?: string): string => {
+  const content = ref
+    ? capture('git', ['show', `${ref}:package.json`])
+    : fs.readFileSync('package.json', 'utf8');
+  return JSON.parse(content).version;
+};
+
+// EXECUTION
+
+const marker = gitPath(markerFile);
+const argBranch = process.argv[2] ?? '';
+const branch = argBranch ||
+  (fs.existsSync(marker) ? fs.readFileSync(marker, 'utf8').trim() : '');
+if (!branch) {
+  console.error('No feature branch recorded. Run prePR first, or pass the branch name: npm run postPR -- <branch>');
+  process.exit(1);
+}
+if (branch === 'main') {
+  console.error('Refusing to treat main as the feature branch');
+  process.exit(1);
+}
+if (!capture('git', ['branch', '--list', branch])) {
+  console.error(`Branch ${branch} does not exist locally; it may already have been deleted`);
+  process.exit(1);
+}
+requireCleanTree();
+run('git', ['checkout', 'main']);
+run('git', ['pull', '--ff-only']);
+// Aborts if the pull request has not been merged: under squash-merges the feature branch is never an ancestor of main, so version equality is the merge check.
+const branchVersion = versionOf(branch);
+const mainVersion = versionOf();
+if (branchVersion !== mainVersion) {
+  console.error(`main is at version ${mainVersion} but ${branch} is at ${branchVersion}; merge the pull request first`);
+  process.exit(1);
+}
+run('npm', ['publish']);
+// Branch cleanup is best-effort: deletion must precede pruning, because "git branch -d" checks mergedness against the upstream ref, which pruning would remove.
+const deleted = spawnSync('git', ['branch', '-d', branch], {stdio: 'inherit'});
+if (deleted.status !== 0) {
+  console.warn(`Could not delete ${branch}; delete it manually after confirming the merge`);
+}
+if (spawnSync('git', ['remote', 'prune', 'origin'], {stdio: 'inherit'}).status !== 0) {
+  console.warn('git remote prune origin failed');
+}
+fs.rmSync(marker, {force: true});
+console.log('Release complete');

package/scripts/prePR.ts

@@ -0,0 +1,64 @@
+/*
+  prePR.ts
+  Prepares a release pull request on the current feature branch: verifies a clean working tree, bumps the package version (the npm "version" hook regenerates openapi.yaml, server.json, and lhm.plugin.json), commits and pushes the result, records the branch name for postPR.ts, and prints the remaining manual steps.
+*/
+
+// IMPORTS
+
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// CONSTANTS
+
+const levels = ['major', 'minor', 'patch'];
+const usage = 'Usage: npm run prePR -- <major|minor|patch>';
+const markerFile = 'kilotest-pr-branch';
+
+// FUNCTIONS
+
+// Runs a command with inherited stdio and throws on failure.
+const run = (command: string, args: string[]): void => {
+  if (spawnSync(command, args, {stdio: 'inherit'}).status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+};
+// Runs a command and returns its trimmed standard output.
+const capture = (command: string, args: string[]): string => {
+  const result = spawnSync(command, args, {encoding: 'utf8'});
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+  return result.stdout.trim();
+};
+// Returns the absolute path of a file inside the git directory.
+const gitPath = (name: string): string =>
+  path.join(capture('git', ['rev-parse', '--absolute-git-dir']), name);
+// Exits unless the working tree is clean, so all substantive changes are committed before the version bump.
+const requireCleanTree = (): void => {
+  const dirty = capture('git', ['status', '--porcelain']);
+  if (dirty) {
+    console.error(`Working tree is not clean. Commit or stash all changes first:\n${dirty}`);
+    process.exit(1);
+  }
+};
+
+// EXECUTION
+
+const level = process.argv[2] ?? '';
+if (!levels.includes(level)) {
+  console.error(usage);
+  process.exit(1);
+}
+const branch = capture('git', ['branch', '--show-current']);
+if (!branch || branch === 'main') {
+  console.error('prePR must run on a feature branch, not on main');
+  process.exit(1);
+}
+requireCleanTree();
+run('npm', ['version', level, '--no-git-tag-version']);
+run('git', ['add', '-A']);
+run('git', ['commit', '-m', 'update version and generated files']);
+run('git', ['push', '-u', 'origin', branch]);
+fs.writeFileSync(gitPath(markerFile), `${branch}\n`);
+console.log('Submit a pull request, merge it to main, then run: npm run postPR');