fix(engines): declare the Node floor the CLI actually starts on, >=20.12.0 (PHARN-06)

[PrzemekGalarowicz]

What this changes

package.json declared engines.node: ">=20", but the CLI does not start on Node 20.0–20.11. Two runtime dependencies, @clack/prompts and @clack/core, declare ">= 20.12.0" and import styleText from node:util. On older Node 20 releases even pharn --version fails while loading, with SyntaxError: … does not provide an export named 'styleText'. npm only prints EBADENGINE warnings during install, so users end up with a CLI that cannot run.

• Declared floor: engines.node is now ">=20.12.0", in package.json and in the root entry of package-lock.json.
• New test tests/engines.test.ts: reads the installed runtime dependencies (including their own dependencies) and fails if any of them requires a newer Node than we declare. It fails on the old >=20. It also checks that the README badge shows the same version.
• New workflow .github/workflows/node-floor.yml: a job named Smoke (node 20.12.0). It builds the package on Node 24, packs it with npm pack, installs the result on exactly Node 20.12.0, and runs pharn --version and pharn --help. It is a separate workflow so the six required jobs in ci.yml keep their names, as docs/contributing.md requires. This job is not a required check.
• Updated check: .dev/floor/check-run-pins.test.mjs counts how many workflow steps install packages from a lockfile or a local path. The count goes from 7 to 9 because of the new workflow, and the test records why.
• Docs: >=20 corrected in the README badge and "Current scope", docs/getting-started.md, docs/troubleshooting.md, docs/contributing.md, SECURITY.md, CLAUDE.md, and the header comment in ci.yml.

Built with /pharn-dev-ship; stage artifacts are in .dev/features/engines-node-floor/. Results:

• validate: exit 0
• regress: no-regressions
• verify: PASS

The first regress/verify run was red, and I fixed both causes before pushing:

• The action-pin checker flagged npx pharn, so the workflow now runs ./node_modules/.bin/pharn directly.
• Markdown lint failed on table alignment in two doc tables.

Type of change

• feat — new stack option, wizard step, or command capability
• fix — bug fix
• docs — docs-only change
• chore / refactor — tooling or internal restructure, no behavior change

Area(s) touched

package metadata | tests | repo tooling (new workflow) | docs

Checklist

• Read the existing file(s) before editing; followed the ESM .js-extension import convention.
• Added tests; they fail on the old >=20.
• Updated the relevant docs/ pages.
• Preserved the security invariants. The new workflow only has contents: read and uses the same pinned action SHAs as floor.yml.

Quality gates

• npm run check passes locally (1335/1335; non-root user, node 22).
• npm run build succeeds, and the packed CLI started on local Node 20.20.2 (0.5.0).
• npm run test:coverage passes (left to CI).

Notes for the reviewer

• The lockfile edit was made by hand. Only one line of package-lock.json changes (the root engines). The only npm available locally is npm 10, which would also have rewritten unrelated libc fields, so I edited that single line directly.
• Optional follow-up for a maintainer: add Smoke (node 20.12.0) to the main ruleset's required checks.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TvcuVhk8hTeDskp5pAJhnc

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 47b78d9e-a315-4aaa-82e1-60c8729cc6c1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}