Upgrading to ShieldCortex 5.0

Read this before you run npm install -g shieldcortex. 5.0 is a breaking release. It will not install on Node 20.

Should I update?

Run node -v, then:

  • 22.14 or newer 22.x — fine. Install 5.0.
  • 24.x — fine. This is the line 5.0 was built to un-break.
  • 20.x — install refuses. Upgrade Node first, or stay on 4.54.15 with npm install -g shieldcortex@4.
  • 23.x — not supported (never was). Use 22 LTS or 24.

What breaks

That is the whole list.

  1. Node 20 is gone. The database engine moved to better-sqlite3 13, which needs Node-API 10. Node 20 does not have it.
  2. Node 23 is not supported. Same reason.
  3. Three Express 5 behaviour changes for anyone calling the dashboard HTTP API directly (scripts, curl, integrations). The dashboard UI itself is unaffected. Nested bracket query strings, empty JSON bodies, and unhandled errors all change. Details are in the full upgrade notes.

What is not breaking, but you should know

  • Action Guard stays off by default. 4.54.15 already did this. 5.0 does not turn it back on. Existing hosts with actionGuard.enabled: true stay on.
  • Automatic memory-injection scanning stays off.

Step by step

cp -a ~/.shieldcortex ~/.shieldcortex.bak-$(date +%Y%m%d)
node -v                                 # must be 22.14+ or 24
npm install -g shieldcortex@5
shieldcortex doctor

Schema migrations are forward-only. We have not verified that a 5.0 database opens cleanly in 4.x — back up first.

Stay on 4.x / roll back

npm install -g shieldcortex@4           # last 4.x is 4.54.15

Until 5.0 is on npm, npm install -g shieldcortex still gives you 4.54.15. Pin it if you do not want 5.0 the next time you type @latest.

Canonical notes (also ships inside the npm package): docs/UPGRADING-5.md.