build!: drop Node.js 20, require 22.12.0 or newer

.changeset/drop-node-20.md

@@ -0,0 +1,5 @@
+---
+'@fission-ai/openspec': minor
+---
+
+**Breaking:** the npm package now needs Node.js 22.12.0 or newer. Node 20 reached end-of-life on April 30, 2026. If you can't upgrade, install the standalone binary (`curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh`, or `irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex` on Windows), which runs without Node. Homebrew (`brew install openspec`) still runs on Node, but installs and manages a current Node.js for you as a dependency.

.devcontainer/README.md

@@ -4,7 +4,7 @@ This directory contains the VS Code dev container configuration for OpenSpec dev
 
 ## What's Included
 
-- **Node.js 22 LTS** - TypeScript/JavaScript runtime (OpenSpec itself supports Node 20.19.0 and newer)
+- **Node.js 22 LTS** - TypeScript/JavaScript runtime (OpenSpec itself supports Node 22.12.0 and newer)
 - **pnpm** - Fast, disk space efficient package manager
 - **Git + GitHub CLI** - Version control tools
 - **VS Code Extensions**:

.github/dependabot.yml

@@ -33,10 +33,6 @@ updates:
       - dependency-name: "@types/node"
         update-types:
           - version-update:semver-major
-      # Chalk 6 requires Node 22, while the published CLI supports Node 20.19.
-      - dependency-name: "chalk"
-        update-types:
-          - version-update:semver-major
       - dependency-name: "typescript"
         update-types:
           - version-update:semver-major

.github/workflows/binaries.yml

@@ -42,7 +42,7 @@ jobs:
       # written by a pull request run could poison them.
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20.19.0'
+          node-version: '22.12.0'
           package-manager-cache: false
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
@@ -223,7 +223,7 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         if: matrix.alpine == ''
         with:
-          node-version: '20.19.0'
+          node-version: '22.12.0'
           package-manager-cache: false
       - name: CLI test suite and `openspec install` against the binary
         run: |

.github/workflows/ci.yml

@@ -61,17 +61,17 @@ jobs:
           - os: ubuntu-latest
             shell: bash
             label: linux-bash
-            node: '20.19.0'
+            node: '22.12.0'
             vitest_workers: 4
           - os: macos-latest
             shell: bash
             label: macos-bash
-            node: '20.19.0'
+            node: '22.12.0'
             vitest_workers: 4
           - os: windows-latest
             shell: pwsh
             label: windows-pwsh
-            node: '20.19.0'
+            node: '22.12.0'
             vitest_workers: 2
           - os: ubuntu-latest
             shell: bash
@@ -120,7 +120,7 @@ jobs:
         run: pnpm test
 
       - name: Upload test coverage
-        if: matrix.os == 'ubuntu-latest' && matrix.node == '20.19.0'
+        if: matrix.os == 'ubuntu-latest' && matrix.node == '22.12.0'
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: coverage-report-${{ github.event_name }}
@@ -156,7 +156,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
-          node-version: '20.19.0'
+          node-version: '22.12.0'
           cache: 'pnpm'
 
       - name: Install dependencies

.github/workflows/security.yml

@@ -58,7 +58,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
-          node-version: '20.19.0'
+          node-version: '22.12.0'
 
       # Advisory on pull requests: a newly published advisory should not stop an
       # unrelated change, and the step depends on registry availability.
@@ -114,7 +114,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
-          node-version: '20.19.0'
+          node-version: '22.12.0'
 
       - name: Verify website lockfile matches package.json
         run: pnpm install --frozen-lockfile --ignore-scripts --dir website

CONTRIBUTING.md

@@ -35,7 +35,7 @@ Opening pull requests is limited to maintainers, so wait for an invitation on th
 
 ## Development setup
 
-You need Node 20.19+ and pnpm.
+You need Node 22.12+ and pnpm.
 
 ```bash
 pnpm install

README.md

@@ -131,7 +131,7 @@ Windows (PowerShell):
 irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
 ```
 
-Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 20.19.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
+Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 22.12.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
 
 Then navigate to your project directory and initialize:
 

docs-lab/start/installation.md

@@ -72,7 +72,7 @@ curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md
 That fetches [install.md at the repo root](https://github.com/Fission-AI/OpenSpec/blob/main/install.md), a prompt written for any agent that can run shell commands (a few IDE integrations can't). Expect your assistant to:
 
 1. Skip the install if the CLI is already on your machine, and offer to update it the way it was installed. If that was npm or Homebrew, mention once that `openspec install` switches to the standalone install, without pushing it. Otherwise, show you the install command above and wait for your confirmation before running it.
-2. Use npm instead only if you ask for it or the installer fails, and stop if your Node is older than 20.19.0.
+2. Use npm instead only if you ask for it or the installer fails, and stop if your Node is older than 22.12.0.
 3. Verify `openspec` is on your PATH.
 4. Name the folder it thinks you mean, suggest the AI tool you're already talking to, and ask which others you use, then run `openspec init` there (the [project setup](setup.md) step).
 5. Report what init created and the exact spelling to invoke OpenSpec in your tool.
@@ -83,13 +83,13 @@ This install method is new and can have varying results depending on model used.
 
 ## Package managers
 
-These install OpenSpec as a Node.js package, so they need Node.js 20.19.0 or newer (Homebrew and Nix bring their own). In your terminal:
+These install OpenSpec as a Node.js package, so they need Node.js 22.12.0 or newer (Homebrew and Nix bring their own). In your terminal:
 
 ```bash
 node --version
 ```
 
-If that prints `v20.19.0` or higher, install with npm:
+If that prints `v22.12.0` or higher, install with npm:
 
 ```npm
 npm install -g @fission-ai/openspec@latest

docs/installation.md

@@ -53,7 +53,7 @@ order, and stop where a step tells you to stop.
    If I'd rather use a package manager, or the installer fails, go to step 2.
 
 2. PACKAGE MANAGER (only if step 1 did not install it). Run `node --version`:
-   this needs Node.js 20.19.0 or higher. If Node is missing or older, say so and
+   this needs Node.js 22.12.0 or higher. If Node is missing or older, say so and
    stop — don't install Node, switch versions, or reconfigure my version
    manager for me. Otherwise use whichever package manager is already on my
    PATH, preferring npm:
@@ -118,7 +118,7 @@ Nothing in the prompt is vendor-specific: it's plain instructions plus the same
 
 ## Package Managers
 
-Installing with a package manager needs **Node.js 20.19.0 or higher** (check with `node --version`).
+Installing with a package manager needs **Node.js 22.12.0 or higher** (check with `node --version`).
 
 ### npm
 
@@ -160,7 +160,7 @@ Note: If your subcommands launch external tools, like config edit, feedback, or
 ### bun
 
 Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.
-You still need Node.js 20.19.0 or higher available on `PATH`.
+You still need Node.js 22.12.0 or higher available on `PATH`.
 
 ```bash
 bun add -g @fission-ai/openspec@latest

docs/troubleshooting.md

@@ -17,15 +17,17 @@ If it installed but still isn't found, your global npm bin directory probably is
 
 If you used the [AI-assisted install](installation.md#install-with-your-ai-assistant), this is the expected hand-off point: that prompt tells your assistant to show you the `PATH` change rather than edit your shell startup files itself.
 
-### "Requires Node.js 20.19.0 or higher"
+### "Requires Node.js 22.12.0 or higher"
 
-OpenSpec runs on Node 20.19.0+. Check your version and upgrade if needed:
+OpenSpec runs on Node 22.12.0+ (Node 20 reached end-of-life in April 2026 and is no longer supported). Check your version and upgrade if needed:
 
 ```bash
 node --version
 ```
 
-If you use bun to install OpenSpec, note that OpenSpec still *runs* on Node, so you need Node 20.19.0+ available on your `PATH` regardless. See [Installation](installation.md).
+If you use bun to install OpenSpec, note that OpenSpec still *runs* on Node, so you need Node 22.12.0+ available on your `PATH` regardless. See [Installation](installation.md).
+
+If you can't upgrade Node, install the [standalone binary](installation.md), which runs without Node. Homebrew is another option: it still runs OpenSpec on Node, but installs and manages a current Node.js for you as a dependency.
 
 ### `openspec init` didn't configure my AI tool
 

install.md

@@ -39,7 +39,7 @@ If the user would rather use a package manager, or the installer fails, continue
 
 ## 2. Package manager (only if step 1 did not install it)
 
-Run `node --version`. Installing with a package manager needs Node.js 20.19.0 or higher. If Node is missing or older, don't install Node, switch versions, or reconfigure the user's version manager yourself; stop and leave them with their next move: https://nodejs.org, or, if they use a version manager like nvm, the command that would switch to a newer version.
+Run `node --version`. Installing with a package manager needs Node.js 22.12.0 or higher. If Node is missing or older, don't install Node, switch versions, or reconfigure the user's version manager yourself; stop and leave them with their next move: https://nodejs.org, or, if they use a version manager like nvm, the command that would switch to a newer version.
 
 Use whichever package manager is already on PATH, preferring npm:
 

openspec/config.yaml

@@ -1,7 +1,7 @@
 schema: spec-driven
 
 context: |
-  Tech stack: TypeScript, Node.js (≥20.19.0), ESM modules
+  Tech stack: TypeScript, Node.js (≥22.12.0), ESM modules
   Package manager: pnpm
   CLI framework: Commander.js
 

package.json

@@ -57,7 +57,7 @@
     "changeset": "changeset"
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.0",

scripts/binary/install.ps1

@@ -41,7 +41,7 @@
   $releases = if ($env:OPENSPEC_RELEASES_URL) { $env:OPENSPEC_RELEASES_URL.TrimEnd('/') } else { 'https://github.com/Fission-AI/OpenSpec/releases' }
   Assert-Source 'OPENSPEC_RELEASES_URL' $releases
   if ($env:OPENSPEC_DOWNLOAD_URL) { Assert-Source 'OPENSPEC_DOWNLOAD_URL' $env:OPENSPEC_DOWNLOAD_URL }
-  $npmHint = 'Or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec'
+  $npmHint = 'Or install with npm (Node.js 22.12+): npm install -g @fission-ai/openspec'
   $dir = if ($env:OPENSPEC_INSTALL_DIR) { $env:OPENSPEC_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA 'Programs\openspec' }
   # Absolute, so the user PATH entry works from any directory.
   $dir = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($dir)

scripts/binary/install.sh

@@ -108,7 +108,7 @@ main() {
     fi
   }
 
-  npm_hint="or install with npm (Node.js 20.19+): npm install -g @fission-ai/openspec"
+  npm_hint="or install with npm (Node.js 22.12+): npm install -g @fission-ai/openspec"
   if [ -n "${OPENSPEC_DOWNLOAD_URL:-}" ]; then
     base=${OPENSPEC_DOWNLOAD_URL%/}
   elif [ "$version" != latest ]; then