From 27ef5328c6d04dfefc45ba702756d6779d0b34b3 Mon Sep 17 00:00:00 2001 From: Mark Beacom Date: Sat, 25 Jul 2026 23:19:00 -0400 Subject: [PATCH 1/3] chore(release): prepare v0.2.1 Bump the coordinated public packages, CLI/MCP runtime version literals, and MCP registry manifest to 0.2.1. Add the v0.2.1 changelog and maintainer cutover runbook, and document the MCP registry and queue@v0 follow-ups. Release-path audit found the MCP server runtime version was not tied to the package version; add coverage and align it before publication. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 36 ++++++++- README.md | 2 +- bun.lock | 8 +- docs/DISTRIBUTION.md | 37 ++++----- docs/RELEASING.md | 107 ++++++++++++++++++++++++++- package.json | 2 +- packages/cli/package.json | 2 +- packages/cli/src/index.ts | 2 +- packages/core/package.json | 2 +- packages/evaluator/package.json | 2 +- packages/mcp/package.json | 2 +- packages/mcp/server.json | 4 +- packages/mcp/src/server.ts | 2 +- packages/mcp/test/version.test.ts | 13 ++++ site/public/llms.txt | 2 +- site/scripts/og-card.svg | 2 +- site/src/components/Hero.astro | 2 +- site/src/content/docs/ci.mdx | 2 +- site/src/content/docs/index.mdx | 2 +- site/src/content/docs/quickstart.mdx | 2 +- 20 files changed, 192 insertions(+), 41 deletions(-) create mode 100644 packages/mcp/test/version.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index e0a6fd4..d68264d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ Until `1.0.0`, minor releases may include breaking changes ## [Unreleased] +## [0.2.1] - 2026-07-25 + ### Added - `adr queue` — emit the ARB operations queue, a read-only, deterministic @@ -20,11 +22,42 @@ Until `1.0.0`, minor releases may include breaking changes default `GITHUB_TOKEN` with `issues: write`. Landed and maintainer reference-verified; external validation is tracked as open ([ADR-0014](docs/adr/0014-stage-phase-landing-evidence-across-a-three-rung-validation-ladder.md)). +- MCP registry distribution metadata: `@adrkit/mcp` declares + `mcpName: dev.adrkit/mcp`, `packages/mcp/server.json` points at the 0.2.1 npm + package, and the repository includes Smithery and Glama manifests plus a + distribution playbook. + +### Changed + +- Hardened CI and release posture: every GitHub Action reference is pinned to a + full commit SHA, checkout credentials are not persisted into the worktree, and + the release job injects its push credential only for the moving major Action tag + update. +- Added a fail-closed `bun audit` gate that treats malformed audit output, + unexpected schema shapes, unknown arguments, and any advisory as CI failures. +- Refreshed public README/site/package docs so Node-targeted `npx`/`npm` install + paths are first-class while Bun remains the repository development toolchain. + +### Fixed + +- `adr --help`, `adr help`, and `adr --version` now work and exit successfully. +- `adr check`, `adr explain`, and the governing-decisions CI Action no longer + report `rejected`, `superseded`, or `deprecated` ADRs as governing active code; + their output now includes status where it affects interpretation. +- `adr migrate --from madr` preserves more legacy MADR/Nygard status and decider + forms, including MADR 2.x `* Deciders:` header bullets, and avoids creating + records that adrkit discovery cannot see. +- `adr queue` reports skipped or undiscoverable ADR files instead of silently + omitting them from the operations queue. +- The MCP server reports a runtime `SERVER_INFO.version` matching the published + package version. ### Security - Bumped `sharp` to `^0.35.0` in the docs site to patch [GHSA-f88m-g3jw-g9cj](https://github.com/advisories/GHSA-f88m-g3jw-g9cj). +- Added root overrides for vulnerable transitive releases of `fast-uri` and + `@hono/node-server`, yielding a clean root `bun audit` before release. ## [0.2.0] - 2026-07-20 @@ -59,6 +92,7 @@ Until `1.0.0`, minor releases may include breaking changes - Node-targeted published distribution of all packages, smoke-tested under Node 22 and 24. -[Unreleased]: https://github.com/mbeacom/adrkit/compare/v0.2.0...HEAD +[Unreleased]: https://github.com/mbeacom/adrkit/compare/v0.2.1...HEAD +[0.2.1]: https://github.com/mbeacom/adrkit/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/mbeacom/adrkit/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/mbeacom/adrkit/releases/tag/v0.1.0 diff --git a/README.md b/README.md index 588e1aa..88741e1 100644 --- a/README.md +++ b/README.md @@ -188,7 +188,7 @@ different artifact from a heading convention. That is the whole thesis. Early, under active development, and deliberately honest about what is proven. -- **Published — v0.2.0 on npm.** The schema, `@adrkit/core`, `@adrkit/cli`, +- **Published — v0.2.1 on npm.** The schema, `@adrkit/core`, `@adrkit/cli`, the deterministic Pass 0 `@adrkit/evaluator`, and the read-only `@adrkit/mcp` server are all implemented and released; the MCP server passed real-session dogfood through the official MCP Inspector. diff --git a/bun.lock b/bun.lock index b639502..e4093a3 100644 --- a/bun.lock +++ b/bun.lock @@ -24,7 +24,7 @@ }, "packages/cli": { "name": "@adrkit/cli", - "version": "0.2.0", + "version": "0.2.1", "bin": { "adr": "./dist/index.js", }, @@ -38,7 +38,7 @@ }, "packages/core": { "name": "@adrkit/core", - "version": "0.2.0", + "version": "0.2.1", "dependencies": { "picomatch": "^4", "semver": "^7", @@ -53,7 +53,7 @@ }, "packages/evaluator": { "name": "@adrkit/evaluator", - "version": "0.2.0", + "version": "0.2.1", "dependencies": { "@adrkit/core": "workspace:*", "jsonpath-rfc9535": "1.3.0", @@ -64,7 +64,7 @@ }, "packages/mcp": { "name": "@adrkit/mcp", - "version": "0.2.0", + "version": "0.2.1", "bin": { "adrkit-mcp": "./dist/bin.js", }, diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md index c906b21..32bcafe 100644 --- a/docs/DISTRIBUTION.md +++ b/docs/DISTRIBUTION.md @@ -27,11 +27,12 @@ GitHub repo, so a small number of prerequisites unblock several venues at once. ### P1 — npm packages are published `@adrkit/mcp`, `@adrkit/cli`, `@adrkit/core`, `@adrkit/evaluator` are published at -`0.2.0` (verify with `npm view @adrkit/mcp version`). The MCP registry hosts -*metadata only*; the npm package must already exist at the version named in -`server.json`. +`0.2.0`; the v0.2.1 release is required before the registry submission below +because `server.json` now names `0.2.1`. The MCP registry hosts *metadata only*; +the npm package must already exist at the exact version named in `server.json` +(verify with `npm view @adrkit/mcp@0.2.1 version` after the release). -### P2 — `mcpName` in the **published** `@adrkit/mcp` (REQUIRED, not yet satisfied) +### P2 — `mcpName` in the **published** `@adrkit/mcp` (REQUIRED; satisfied only after v0.2.1 publishes) The official registry verifies npm ownership by reading `mcpName` from the package metadata of the **exact published version** named in `server.json` — not @@ -59,14 +60,14 @@ now declares `"mcpName": "dev.adrkit/mcp"`): **Publishing therefore requires, in order:** 1. Merge the manifest change and cut a **new release** (e.g. `v0.2.1`) so a - published version of `@adrkit/mcp` carries `mcpName`. + published version of `@adrkit/mcp` carries `mcpName` and matches `server.json`. 2. Confirm it landed: `npm view @adrkit/mcp@0.2.1 mcpName` → `dev.adrkit/mcp`. -3. Bump **both** version fields in `packages/mcp/server.json` — the top-level - `version` and `packages[0].version` — to that same new version. +3. Confirm **both** version fields in `packages/mcp/server.json` — the top-level + `version` and `packages[0].version` — name that same published version. 4. Only then run `mcp-publisher publish`. -Publishing against `server.json` as currently pinned (0.2.0) will fail -ownership validation no matter what the working tree says. +Publishing against a `server.json` version that is not yet on npm will fail +validation no matter what the working tree says. `server.json` does **not** need to be added to the package's `files` allowlist — `mcp-publisher` reads it from the working directory at publish time and it is not @@ -178,7 +179,7 @@ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.adrkit/mc "name": "dev.adrkit/mcp", "title": "adrkit decision memory", "description": "Deterministic, offline, read-only ADR decision memory for coding agents. No model or network calls.", - "version": "0.2.0", + "version": "0.2.1", "websiteUrl": "https://adrkit.dev", "repository": { "url": "https://github.com/mbeacom/adrkit", @@ -190,7 +191,7 @@ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.adrkit/mc "registryType": "npm", "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@adrkit/mcp", - "version": "0.2.0", + "version": "0.2.1", "runtimeHint": "npx", "transport": { "type": "stdio" }, "environmentVariables": [ @@ -206,9 +207,10 @@ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.adrkit/mc > release you are publishing. If a new release (e.g. the SDK-CVE patch) bumps > `@adrkit/mcp`, bump both fields here before re-publishing. -**Listing criteria met?** Yes — schema-valid, npm package exists, stdio transport, -public repo. The only blocker is the human steps above (namespace proof + the P2 -`mcpName` edit). +**Listing criteria met?** Yes once v0.2.1 is published — schema-valid, npm package +exists at the manifest version, stdio transport, public repo. The remaining +blockers are the human namespace proof and the v0.2.1 npm publication that carries +`mcpName`. --- @@ -550,9 +552,10 @@ procedure only; the release is a human action. ## E. Changes needed from other workstreams (report only) -| File (not owned here) | Needed change | Why | -|---|---|---| -| `packages/mcp/package.json` | Add `"mcpName": "dev.adrkit/mcp"` (must equal `server.json` `name`). | Required for official MCP registry npm-ownership verification (P2). | +No distribution-blocking source edits are currently delegated to another +workstream. `packages/mcp/package.json` now declares +`"mcpName": "dev.adrkit/mcp"` (matching `server.json` `name`); v0.2.1 must be cut +so that field exists in npm metadata. `server.json` does **not** need to be added to `packages/mcp/package.json` `files`. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 69e0e66..375522b 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -9,7 +9,7 @@ Action: | `@adrkit/evaluator` | npm | | `@adrkit/cli` (`adr`) | npm | | `@adrkit/mcp` (`adrkit-mcp`) | npm | -| `packages/ci/action.yml` | Git tag (latest immutable release `v0.2.0`, moving `v0`) | +| `packages/ci/action.yml` | Git tag (latest immutable release `v0.2.1`, moving `v0`) | `@adrkit/ci` stays private because GitHub executes the committed Action bundle directly from the referenced repository ref. @@ -48,7 +48,7 @@ From a clean checkout: ```sh bun install --frozen-lockfile -bun run release:pack -- --tag v0.2.0 +bun run release:pack -- --tag v0.2.1 # With Node 22 selected in your Node version manager: node .release/smoke/smoke.mjs "$PWD" # Switch the same shell to Node 24, then run: @@ -99,7 +99,7 @@ bootstrap described below. inter-package expectations and run `bun install` with stable Bun 1.3.14 when the lockfile changes. 2. Merge the version change only after CI passes. -3. Create and push the matching annotated tag, such as `v0.2.0`. +3. Create and push the matching annotated tag, such as `v0.2.1`. 4. Approve the protected `npm` environment deployment. 5. Confirm the workflow published all packages, created the immutable GitHub release, and moved `v0` to the released commit. @@ -107,6 +107,107 @@ bootstrap described below. Never move an immutable `vX.Y.Z` tag. The release workflow may force-update only the moving major Action tag (`v0`, later `v1`, and so on). +## v0.2.1 cutover runbook + +Run these steps only after the version-bump PR is the last change merged to +`main`. If `audit-gate-published-scope`, `wave3-toward-1-0`, or +`adr-0015-decision` lands first, refresh the changelog and re-run the local +simulation before tagging. + +1. Start from the final release commit on `main`. + + ```sh + git switch main + git pull --ff-only origin main + git log -1 --oneline + ``` + + Verify that the last commit is the intended v0.2.1 release-prep commit. + +2. Re-run the local release simulation. + + ```sh + bun install --frozen-lockfile + bun run release:pack -- --tag v0.2.1 + # With Node 22 selected: + node .release/smoke/smoke.mjs "$PWD" + # With Node 24 selected: + node .release/smoke/smoke.mjs "$PWD" + bun .release/smoke/smoke.mjs "$PWD" + bun run release:publish -- --dry-run + ``` + + Verify that all commands exit 0 and `.release/npm/manifest.json` lists + `version: "0.2.1"` for all four public packages. + +3. Create and push the immutable release tag. + + ```sh + git tag -a v0.2.1 -m "adrkit v0.2.1" + git push origin v0.2.1 + ``` + + Verify the release workflow started: + + ```sh + gh run list --workflow release.yml --event push --limit 1 + ``` + +4. Approve the protected `npm` environment deployment in GitHub Actions. + + Verify the release workflow succeeds: + + ```sh + gh run list --workflow release.yml --event push --status success --limit 1 + ``` + +5. Confirm all npm packages and the MCP ownership metadata are published. + + ```sh + for package in @adrkit/core @adrkit/evaluator @adrkit/cli @adrkit/mcp; do + npm view "${package}@0.2.1" version + done + npm view @adrkit/mcp@0.2.1 mcpName + ``` + + Verify the first loop prints `0.2.1` four times and the MCP metadata prints + `dev.adrkit/mcp`. + +6. Confirm the GitHub release and moving major Action tag. + + ```sh + gh release view v0.2.1 + git ls-remote --tags origin refs/tags/v0 refs/tags/v0.2.1 'refs/tags/v0.2.1^{}' + gh api 'repos/mbeacom/adrkit/contents/packages/ci/queue/action.yml?ref=v0' --jq .path + ``` + + Verify the release exists, `v0` resolves to the v0.2.1 release commit, and the + contents API prints `packages/ci/queue/action.yml`. + +7. Publish the official MCP registry entry after the npm checks pass. + + ```sh + cd packages/mcp + mcp-publisher publish + curl 'https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.adrkit/mcp' + ``` + + Verify the registry response includes `dev.adrkit/mcp` and package version + `0.2.1`. If namespace proof has not been completed yet, follow + [`docs/DISTRIBUTION.md`](./DISTRIBUTION.md) section A before publishing. + +8. De-pin queue Action examples only after `queue@v0` resolves. + + ```sh + gh api 'repos/mbeacom/adrkit/contents/packages/ci/queue/action.yml?ref=v0' --jq .sha + rg 'mbeacom/adrkit/packages/ci/queue@efef89b5d747ca175a1947f1ce2f4296dab54fa3' + ``` + + Verify the contents API returns the queue Action blob SHA. Then update + copy-pasteable documentation examples from the full commit pin to + `mbeacom/adrkit/packages/ci/queue@v0`; keep immutable pins where the text is + explicitly teaching reproducibility. + ### One-time `@adrkit/mcp` bootstrap for v0.2.0 (completed) This step is **done** and is kept only as a record. The workflow no longer diff --git a/package.json b/package.json index 7907f2c..da6c606 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "adrkit", - "version": "0.2.0", + "version": "0.2.1", "description": "Decision memory for human and agent-authored plans — machine-readable, CI-enforceable architecture decision records.", "type": "module", "private": true, diff --git a/packages/cli/package.json b/packages/cli/package.json index f2b0b2f..65d5752 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@adrkit/cli", - "version": "0.2.0", + "version": "0.2.1", "description": "Git-native architecture decision record tooling from adrkit.", "type": "module", "license": "Apache-2.0", diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index a7665e1..f3b2022 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -28,7 +28,7 @@ import { isMainModule } from './main-module.ts'; * (mirroring `@adrkit/mcp`'s `SERVER_INFO`) so the bundled `dist/index.js` never has * to locate `package.json` at runtime. `version.test.ts` asserts the two agree. */ -export const CLI_VERSION = '0.2.0'; +export const CLI_VERSION = '0.2.1'; function writeStdout(text: string): void { process.stdout.write(text); diff --git a/packages/core/package.json b/packages/core/package.json index e3ba2e5..f3d2f43 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@adrkit/core", - "version": "0.2.0", + "version": "0.2.1", "description": "Pure ADR parsing, validation, migration, and affects resolution for adrkit.", "type": "module", "license": "Apache-2.0", diff --git a/packages/evaluator/package.json b/packages/evaluator/package.json index cac2cb2..d1e385a 100644 --- a/packages/evaluator/package.json +++ b/packages/evaluator/package.json @@ -1,6 +1,6 @@ { "name": "@adrkit/evaluator", - "version": "0.2.0", + "version": "0.2.1", "description": "Deterministic, model-free ADR proposal evaluation and routing for adrkit.", "type": "module", "license": "Apache-2.0", diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 77c9dd7..43839b0 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,7 +1,7 @@ { "name": "@adrkit/mcp", "mcpName": "dev.adrkit/mcp", - "version": "0.2.0", + "version": "0.2.1", "description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.", "type": "module", "license": "Apache-2.0", diff --git a/packages/mcp/server.json b/packages/mcp/server.json index 2bb2db0..7347136 100644 --- a/packages/mcp/server.json +++ b/packages/mcp/server.json @@ -3,7 +3,7 @@ "name": "dev.adrkit/mcp", "title": "adrkit decision memory", "description": "Deterministic, offline, read-only ADR decision memory for coding agents. No model or network calls.", - "version": "0.2.0", + "version": "0.2.1", "websiteUrl": "https://adrkit.dev", "repository": { "url": "https://github.com/mbeacom/adrkit", @@ -15,7 +15,7 @@ "registryType": "npm", "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@adrkit/mcp", - "version": "0.2.0", + "version": "0.2.1", "runtimeHint": "npx", "transport": { "type": "stdio" diff --git a/packages/mcp/src/server.ts b/packages/mcp/src/server.ts index 931b714..3c92b23 100644 --- a/packages/mcp/src/server.ts +++ b/packages/mcp/src/server.ts @@ -14,7 +14,7 @@ import { registerGetDecisionContext } from './tools/get-decision-context.ts'; import { registerListSuperseded } from './tools/list-superseded.ts'; import type { ToolConfig } from './tools/shared.ts'; -export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.1.0' } as const; +export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.2.1' } as const; /** Package-internal: build the concrete server with exactly the four ratified tools. */ export function buildRegisteredServer(config: ToolConfig): McpServer { diff --git a/packages/mcp/test/version.test.ts b/packages/mcp/test/version.test.ts new file mode 100644 index 0000000..87619ab --- /dev/null +++ b/packages/mcp/test/version.test.ts @@ -0,0 +1,13 @@ +import { describe, expect, test } from 'bun:test'; +import { readFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; +import { SERVER_INFO } from '../src/server.ts'; + +const PACKAGE_JSON = resolve(process.cwd(), 'packages/mcp/package.json'); + +describe('SERVER_INFO', () => { + test('matches the published package version', async () => { + const pkg = JSON.parse(await readFile(PACKAGE_JSON, 'utf8')) as { version: string }; + expect(pkg.version).toBe(SERVER_INFO.version); + }); +}); diff --git a/site/public/llms.txt b/site/public/llms.txt index e09d120..6720656 100644 --- a/site/public/llms.txt +++ b/site/public/llms.txt @@ -3,7 +3,7 @@ > Decision memory for human- and agent-authored plans. adrkit turns architecture > decision records into typed, machine-readable data that is enforceable in CI and > legible to agents — without leaving git. Published as `@adrkit/core`, -> `@adrkit/cli`, `@adrkit/evaluator`, and `@adrkit/mcp` (v0.2.0 on npm), plus a +> `@adrkit/cli`, `@adrkit/evaluator`, and `@adrkit/mcp` (v0.2.1 on npm), plus a > GitHub Action at `mbeacom/adrkit/packages/ci@v0`. Key facts an agent should know: diff --git a/site/scripts/og-card.svg b/site/scripts/og-card.svg index 72704d5..36104db 100644 --- a/site/scripts/og-card.svg +++ b/site/scripts/og-card.svg @@ -7,7 +7,7 @@ Typed, locatable ADRs — enforceable in CI, legible to agents. - v0.2.0 on npm · adrkit.dev + v0.2.1 on npm · adrkit.dev CLI · CI · MCP · evaluator diff --git a/site/src/components/Hero.astro b/site/src/components/Hero.astro index 629e017..32acbfc 100644 --- a/site/src/components/Hero.astro +++ b/site/src/components/Hero.astro @@ -14,7 +14,7 @@ const { title = data.title, tagline, actions = [] } = data.hero || {}; CLI works today - v0.2.0 on npm · decision memory in git + v0.2.1 on npm · decision memory in git

diff --git a/site/src/content/docs/ci.mdx b/site/src/content/docs/ci.mdx index 3544d14..8aab25a 100644 --- a/site/src/content/docs/ci.mdx +++ b/site/src/content/docs/ci.mdx @@ -39,7 +39,7 @@ jobs: # token: ${{ github.token }} ``` -`v0` is a moving major tag. Pin the immutable `v0.2.0` tag or a commit SHA for +`v0` is a moving major tag. Pin the immutable `v0.2.1` tag or a commit SHA for maximum reproducibility. ## Publish the ARB operations queue diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx index fee61a2..d1d8661 100644 --- a/site/src/content/docs/index.mdx +++ b/site/src/content/docs/index.mdx @@ -18,7 +18,7 @@ hero:
- Published · v0.2.0 + Published · v0.2.1

@adrkit/core, @adrkit/cli, @adrkit/evaluator, and @adrkit/mcp are on npm; diff --git a/site/src/content/docs/quickstart.mdx b/site/src/content/docs/quickstart.mdx index d25c549..541b3f3 100644 --- a/site/src/content/docs/quickstart.mdx +++ b/site/src/content/docs/quickstart.mdx @@ -10,7 +10,7 @@ decisions govern a file, renders the decision graph, migrates an existing MADR corpus in place, emits the ARB operations queue, and runs the deterministic evaluator. -