@cairnkeep/cli 1.1.3 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [2.0.0] - 2026-07-15
+
+### Breaking
+
+- Require Node.js 22 or newer. Node.js 18 and 20 are end-of-life upstream;
+  Cairnkeep 1.x remains available for machines that cannot upgrade yet.
+
+### Changed
+
+- Upgrade the runtime schema dependency to Zod 4 in both package manifests.
+- Build with TypeScript 7 against Node.js 22 type definitions.
+- Exercise Node.js 22, 24, and 26 on Linux, retain real macOS installation
+  coverage, and verify the packed package at the Node.js 22 runtime floor.
+
+The memory database format, default storage location, remote HTTP protocol,
+and project scaffold format are unchanged. Upgrading does not migrate or delete
+stored memories.
+
 ## [1.1.3] - 2026-07-14
 
 ### Fixed
@@ -51,6 +69,9 @@ All notable user-facing changes are documented here. This project follows
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
+[2.0.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.3...v2.0.0
+[1.1.3]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.2...v1.1.3
+[1.1.2]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.0.5...v1.1.0
 [1.0.5]: https://github.com/cairnkeep/cairnkeep/compare/v1.0.4...v1.0.5

package/CONTRIBUTING.md

@@ -15,9 +15,9 @@ Contributions are welcome through GitHub issues and pull requests.
 
 ## Development setup
 
-The memory server requires Node.js 18 or newer. Node.js 22 or 24 is recommended
-for development; current CI uses Node.js 24 and retains a clean Node.js 18
-compatibility boot check.
+The memory server requires Node.js 22 or newer. CI builds and tests on Node.js
+22, 24, and 26, including a clean packed-install boot check at the Node.js 22
+runtime floor.
 
 ```bash
 git clone https://github.com/cairnkeep/cairnkeep.git

package/README.md

@@ -26,9 +26,9 @@ cairnkeep-org sibling project.
 
 ## Compatibility
 
-Node.js 22 or 24 is recommended. Node.js 18 and 20 remain compatible for the
-1.x line but are end-of-life upstream; the minimum will move in the next major
-release.
+Node.js 22, 24, and 26 are supported. Cairnkeep 2.x requires Node.js 22 or
+newer; Cairnkeep 1.x remains available for older runtimes, although Node.js 18
+and 20 are end-of-life upstream.
 
 | Client or platform | Support level |
 |---|---|
@@ -38,7 +38,7 @@ release.
 | Other MCP clients | Memory and optional domain-knowledge MCP tools |
 | Native Windows | Not supported by the Bash-based installer; use WSL (not yet CI-verified) |
 
-Linux, macOS, Bash 3.2 portability, and a clean Node 18 compatibility install
+Linux, macOS, Bash 3.2 portability, and clean Node 22/24/26 runtime checks
 are exercised in CI.
 
 ## Components

package/docs/operating.md

@@ -16,8 +16,8 @@ installs. This guide covers all three in order.
 
 ## Prerequisites
 
-- Node.js (for the memory server) and a supported harness: Claude Code or
-  OpenCode.
+- Node.js 22 or newer (for the memory server) and a supported harness: Claude
+  Code or OpenCode.
 - Optional: the `sqlite3` CLI for `cairn memory export`. Runtime memory and
   `cairn memory import` do not require it.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and

package/mcp-memory-server/dist/index.js

@@ -13,6 +13,12 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod";
 import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashText, } from "./embeddings.js";
 import { computeRepoState, exploreCacheKey, normalizeExploreQuery, readExploreCache, writeExploreCache, } from "./explore-cache.js";
+const MINIMUM_NODE_MAJOR = 22;
+const nodeMajor = Number.parseInt(process.versions.node, 10);
+if (!Number.isInteger(nodeMajor) || nodeMajor < MINIMUM_NODE_MAJOR) {
+    process.stderr.write(`cairn-memory requires Node.js ${MINIMUM_NODE_MAJOR} or newer; found ${process.versions.node}\n`);
+    process.exit(1);
+}
 class ClientContextError extends Error {
 }
 const moduleDir = dirname(fileURLToPath(import.meta.url));

package/mcp-memory-server/package.json

@@ -5,6 +5,9 @@
     "description": "Durable, harness-agnostic memory MCP server for coding agents — the core of Cairnkeep.",
     "license": "Apache-2.0",
     "type": "module",
+    "engines": {
+        "node": ">=22"
+    },
     "scripts": {
         "build": "tsc -p tsconfig.json",
         "start": "node dist/index.js",
@@ -28,10 +31,10 @@
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
         "agentfs-sdk": "^0.6.4",
-        "zod": "^3.25.76"
+        "zod": "^4.4.3"
     },
     "devDependencies": {
-        "@types/node": "^22.15.21",
-        "typescript": "^5.8.3"
+        "@types/node": "^22.20.1",
+        "typescript": "^7.0.2"
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "1.1.3",
+  "version": "2.0.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,12 +28,12 @@
     "AGENTS.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "agentfs-sdk": "^0.6.4",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   },
   "scripts": {
     "build:server": "npm --prefix mcp-memory-server ci --include=dev --global=false --dry-run=false && npm --prefix mcp-memory-server run build --global=false --dry-run=false",

package/scripts/doctor.sh

@@ -35,7 +35,12 @@ echo "cairn doctor"
 server="$CAIRN_ROOT/mcp-memory-server/dist/index.js"
 probe="$CAIRN_ROOT/scripts/probe-memory-server.mjs"
 if ! command -v node >/dev/null 2>&1; then
-  fail "Node.js not found (Node.js 18 or newer is required)"
+  fail "Node.js not found (Node.js 22 or newer is required)"
+elif ! node_major=$(node -p 'Number(process.versions.node.split(".")[0])' 2>/dev/null) ||
+     [[ ! "$node_major" =~ ^[0-9]+$ ]]; then
+  fail "could not determine the Node.js version (Node.js 22 or newer is required)"
+elif [[ "$node_major" -lt 22 ]]; then
+  fail "Node.js $(node --version 2>/dev/null || printf unknown) is unsupported (Node.js 22 or newer is required)"
 elif [[ ! -f "$server" ]]; then
   fail "memory server not built — run: (cd \"$CAIRN_ROOT/mcp-memory-server\" && npm install && npm run build)"
 elif node "$probe" "$server" >/dev/null 2>&1; then

package/scripts/test-doctor.sh

@@ -17,7 +17,24 @@ proj="$tmp/clean"; mkdir -p "$proj"
 ( cd "$proj" && "$doctor" ) >"$tmp/out1" 2>&1 || fail "doctor exited non-zero with nothing configured:\n$(cat "$tmp/out1")"
 grep -q "\[SKIP\]" "$tmp/out1" || fail "expected SKIP lines when nothing is configured"
 
-# 2. A configured but unreachable endpoint → FAIL + non-zero exit.
+# 2. An unsupported runtime is diagnosed before the server probe.
+mkdir -p "$tmp/old-node"
+cat > "$tmp/old-node/node" <<'EOF'
+#!/usr/bin/env bash
+case "${1:-}" in
+  -p) echo 20 ;;
+  --version) echo v20.19.0 ;;
+  *) exit 1 ;;
+esac
+EOF
+chmod 755 "$tmp/old-node/node"
+if ( cd "$proj" && PATH="$tmp/old-node:$PATH" "$doctor" ) >"$tmp/out-old-node" 2>&1; then
+  fail "doctor should exit non-zero for an unsupported Node.js runtime:\n$(cat "$tmp/out-old-node")"
+fi
+grep -q "Node.js v20.19.0 is unsupported" "$tmp/out-old-node" ||
+  fail "expected a clear unsupported-Node.js diagnostic"
+
+# 3. A configured but unreachable endpoint → FAIL + non-zero exit.
 if command -v curl >/dev/null 2>&1; then
   proj2="$tmp/broken"; mkdir -p "$proj2/.ai"
   echo 'CAIRN_LLM_API_URL=http://127.0.0.1:1' > "$proj2/.ai/.env"

package/scripts/test-runtime-contract.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+node --input-type=module - "$ROOT" <<'EOF'
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = process.argv[2];
+const rootPackage = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const serverPackage = JSON.parse(
+  readFileSync(join(root, "mcp-memory-server", "package.json"), "utf8"),
+);
+
+const failures = [];
+if (rootPackage.engines?.node !== ">=22") failures.push("root Node.js engine must be >=22");
+if (serverPackage.engines?.node !== rootPackage.engines?.node) {
+  failures.push("root and memory-server Node.js engines differ");
+}
+if (rootPackage.dependencies?.zod !== serverPackage.dependencies?.zod) {
+  failures.push("root and memory-server Zod declarations differ");
+}
+if (!rootPackage.dependencies?.zod?.startsWith("^4.")) failures.push("Zod must use major 4");
+if (!serverPackage.devDependencies?.typescript?.startsWith("^7.")) {
+  failures.push("TypeScript must use major 7");
+}
+if (!serverPackage.devDependencies?.["@types/node"]?.startsWith("^22.")) {
+  failures.push("Node.js types must match the Node.js 22 runtime floor");
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) console.error(`FAIL: ${failure}`);
+  process.exit(1);
+}
+EOF
+
+grep -q 'node: \["22", "24", "26"\]' "$ROOT/.github/workflows/ci.yml"
+if grep -Eq 'node-version: "(18|20)"|node:(18|20)-slim' "$ROOT/.github/workflows/ci.yml"; then
+  echo "FAIL: CI still declares an end-of-life Node.js runtime" >&2
+  exit 1
+fi
+
+echo "PASS: runtime and toolchain declarations are aligned"