feat: registry cache, logging, and Changesets release flow

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/early-cache-and-logging.md

@@ -0,0 +1,5 @@
+---
+"check-my-engine": minor
+---
+
+Cache npm registry lookups on disk with a configurable TTL to speed up repeat runs, and add a logging module for diagnostic output.

.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+# Cancel in-progress runs on the same branch.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the "Version Packages" PR and git tags
+      pull-requests: write # open/update the release PR
+      id-token: write # npm provenance / OIDC Trusted Publishing
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: ".nvmrc"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Create release PR or publish to npm
+        uses: changesets/action@e0145edc7d9d8679003495b11f87bd8ef63c0cba # v1.5.3
+        with:
+          version: pnpm run version-packages
+          publish: pnpm run release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: "true"

README.md

@@ -76,6 +76,34 @@ Example output:
 | `--no-suggest`               | Skip registry lookups for in-range versions (offline).                                    |
 | `--allow-prerelease`         | Consider prerelease versions when suggesting.                                             |
 | `--fallback-to-node-modules` | Read engines from `node_modules` when the lockfile omits them (npm only; no-op for pnpm). |
+| `--no-cache`                 | Skip the on-disk registry cache (always hit the network).                                 |
+
+#### Registry cache
+
+Suggestion lookups hit the npm registry once per package name. Responses are
+cached on disk so repeated runs — `postinstall`, CI, watch loops — stay fast and
+avoid registry rate limits. The cache is best-effort: a corrupt or unwritable
+cache degrades to a normal network fetch, never an error.
+
+| Setting                     | Default                                                         | Meaning                                  |
+| --------------------------- | --------------------------------------------------------------- | ---------------------------------------- |
+| `CHECK_MY_ENGINE_CACHE_DIR` | `$XDG_CACHE_HOME/check-my-engine` or `~/.cache/check-my-engine` | Cache directory.                         |
+| `CHECK_MY_ENGINE_CACHE_TTL` | `3600` (seconds)                                                | How long a cached packument stays fresh. |
+| `--no-cache`                | cache on                                                        | Bypass the cache for one run.            |
+
+#### Debug logging
+
+For development, set `NODE_DEBUG=check-my-engine` to trace registry traffic on
+stderr — each network fetch, registry hit, and cache hit. It is silent unless
+the namespace is enabled, so end-user runs (including `postinstall`) print
+nothing, and the trace never touches stdout (safe alongside `--json`).
+
+```shell
+$ NODE_DEBUG=check-my-engine npx check-my-engine
+check-my-engine registry fetch: https://registry.npmjs.org/needs-22
+check-my-engine registry hit: needs-22 (200, 12 versions)
+check-my-engine cache hit: needs-22
+```
 
 ## Enforce on install
 

package.json

@@ -50,7 +50,10 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm build",
-    "check": "node dist/cli.js check"
+    "check": "node dist/cli.js check",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
   },
   "dependencies": {
     "commander": "^15.0.0",
@@ -60,6 +63,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.1",
+    "@changesets/cli": "^2.31.0",
     "@types/node": "^24.13.2",
     "@types/semver": "^7.7.1",
     "prettier": "^3.9.4",