From 18667091ee20c58cd145194c994ae307a6937fa4 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 26 Oct 2026 13:03:55 -0500 Subject: [PATCH 1/3] build!: drop Node.js 20, require 22.12.0 or newer Node 20 reached end-of-life on 2026-04-30. Raises engines, the CI oldest-supported test jobs, the binary/security workflows, the install scripts' npm hint and the install/troubleshooting docs to 22.12.0, and removes the Dependabot chalk-6 ignore that existed only for Node 20. Unblocks vitest 5 (#2151, #2152) and commander 15. Co-Authored-By: Claude Opus 5.5 --- .changeset/drop-node-20.md | 5 +++++ .devcontainer/README.md | 2 +- .github/dependabot.yml | 4 ---- .github/workflows/binaries.yml | 4 ++-- .github/workflows/ci.yml | 10 +++++----- .github/workflows/security.yml | 4 ++-- CONTRIBUTING.md | 2 +- README.md | 2 +- docs-lab/start/installation.md | 6 +++--- docs/installation.md | 6 +++--- docs/troubleshooting.md | 8 +++++--- install.md | 2 +- openspec/config.yaml | 2 +- package.json | 2 +- scripts/binary/install.ps1 | 2 +- scripts/binary/install.sh | 2 +- 16 files changed, 33 insertions(+), 30 deletions(-) create mode 100644 .changeset/drop-node-20.md diff --git a/.changeset/drop-node-20.md b/.changeset/drop-node-20.md new file mode 100644 index 0000000000..235c675a1d --- /dev/null +++ b/.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) or use Homebrew; neither needs Node. diff --git a/.devcontainer/README.md b/.devcontainer/README.md index 1d7201e31a..dc2c9372bc 100644 --- a/.devcontainer/README.md +++ b/.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**: diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 3ffee2ab12..4c933dea23 100644 --- a/.github/dependabot.yml +++ b/.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 diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml index 22cfec30fc..c176c58265 100644 --- a/.github/workflows/binaries.yml +++ b/.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: | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5308c2cf2c..c52ff76af7 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 869bf1b651..749feaaf24 100644 --- a/.github/workflows/security.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a29ae230c2..a053ab576e 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index ce794e0949..bacb65282b 100644 --- a/README.md +++ b/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: diff --git a/docs-lab/start/installation.md b/docs-lab/start/installation.md index 1e228cf821..3f4d58664a 100644 --- a/docs-lab/start/installation.md +++ b/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 diff --git a/docs/installation.md b/docs/installation.md index 759d29414e..fbbe662b73 100644 --- a/docs/installation.md +++ b/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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f35ada883a..8d69f5822b 100644 --- a/docs/troubleshooting.md +++ b/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) or use Homebrew instead; neither needs Node on your machine. ### `openspec init` didn't configure my AI tool diff --git a/install.md b/install.md index 51e73bacc4..12a816ef86 100644 --- a/install.md +++ b/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: diff --git a/openspec/config.yaml b/openspec/config.yaml index 0b7ad5176a..f3c38df10e 100644 --- a/openspec/config.yaml +++ b/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 diff --git a/package.json b/package.json index cf8ce7d03a..d9f13db8ef 100644 --- a/package.json +++ b/package.json @@ -57,7 +57,7 @@ "changeset": "changeset" }, "engines": { - "node": ">=20.19.0" + "node": ">=22.12.0" }, "devDependencies": { "@changesets/changelog-github": "^1.0.0", diff --git a/scripts/binary/install.ps1 b/scripts/binary/install.ps1 index 685fb7e9b5..8853de60a0 100644 --- a/scripts/binary/install.ps1 +++ b/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) diff --git a/scripts/binary/install.sh b/scripts/binary/install.sh index 956b5088cf..84d2128338 100644 --- a/scripts/binary/install.sh +++ b/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 From ce8ef1bf16ec179e55822770cdda386010ae37ce Mon Sep 17 00:00:00 2001 From: Clay Good Date: Wed, 28 Oct 2026 15:03:34 -0500 Subject: [PATCH 2/3] docs: say Homebrew manages Node for you, not that it skips Node The changeset and troubleshooting page said the standalone binary and Homebrew "neither needs Node". The Homebrew formula depends on `node`, so only the standalone binary is Node-free; Homebrew installs and manages a current Node.js as a dependency. Co-Authored-By: Claude Opus 5.5 --- .changeset/drop-node-20.md | 2 +- docs/troubleshooting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/drop-node-20.md b/.changeset/drop-node-20.md index 235c675a1d..a81726e749 100644 --- a/.changeset/drop-node-20.md +++ b/.changeset/drop-node-20.md @@ -2,4 +2,4 @@ '@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) or use Homebrew; neither needs Node. +**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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8d69f5822b..172ae503d6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -27,7 +27,7 @@ node --version 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) or use Homebrew instead; neither needs Node on your machine. +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 From ba9d63b473439eedc53b24896e5320344d9e0a61 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Thu, 29 Oct 2026 14:37:55 -0500 Subject: [PATCH 3/3] docs(changeset): say who the Node 22 floor affects Only npm installs on Node 20, which is already end-of-life, are affected. The standalone binary has been the default install since v1.15.0 and doesn't use Node, and nothing else about the CLI changes. That is why this ships as a minor release. Co-Authored-By: Claude Opus 5.5 --- .changeset/drop-node-20.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/drop-node-20.md b/.changeset/drop-node-20.md index a81726e749..47f763ee95 100644 --- a/.changeset/drop-node-20.md +++ b/.changeset/drop-node-20.md @@ -2,4 +2,4 @@ '@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. +**Breaking:** the npm package now needs Node.js 22.12.0 or newer. Node 20 reached end-of-life on April 30, 2026. Only npm installs on Node 20 are affected: the standalone binary, the default install since v1.15.0, doesn't use Node, and nothing else about the CLI changes. 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). Homebrew (`brew install openspec`) still runs on Node, but installs and manages a current Node.js for you as a dependency.