Skip to content

docs: correct the documented node and pnpm floors - #1658

Merged
Rotorsoft merged 1 commit into
masterfrom
act-1651-toolchain-floor
Sep 9, 2026
Merged

docs: correct the documented node and pnpm floors#1658
Rotorsoft merged 1 commit into
masterfrom
act-1651-toolchain-floor

Conversation

@Rotorsoft

Copy link
Copy Markdown
Owner

Closes #1651

The defect

The pnpm 12 / vitest 5 upgrade raised the enforced floor and left the docs behind. Root engines is { node: ">=22.23.2", pnpm: ">=12.3.3" } with packageManager: pnpm@12.3.3, while:

  • CLAUDE.md:70 said Node ≥ 22.23.1, pnpm ≥ 11.9.0
  • docs/docs/intro.md:102-103 said the same

engines.pnpm is >=12.3.3, so a contributor following either doc and installing pnpm 11.9 hits a hard engine failure at pnpm install. Not merely stale — actively wrong about the supported floor, in the file the AI assistant is told to treat as authoritative for this repo.

What the grep turned up

The ticket's own fix direction said to grep for other copies of the pair, and it found a second surface the ticket hadn't named: every lib README's Compatibility section understates its own package's engines.node.

engines.node README claimed
act, act-crypto, act-diagram, act-http, act-ops, act-patch, act-pino, act-sqlite, act-tck >=22.23.2 >=22.18.0
act-pg >=22.23.2 >=22.23.1

That one matters more than the contributor-facing lines: it is a published claim about what a consumer of the package needs, so it is wrong for readers of the package rather than just for people working in the repo. All ten now match their own engines.

Fixed inline rather than deferred, per the doc-audit rule in CLAUDE.md ("Hits get fixed inline; do not leave them for a 'follow-up PR'").

Deliberately left alone

  • docs/versioned_docs/version-1.x/intro.md — a frozen snapshot of what the released 1.x line required. Rewriting it would make the versioned docs lie about the version they document.
  • libs/act-pg/PERFORMANCE.md:326 — records the Node version a past benchmark actually ran on. That is a measurement record, not a requirement.
  • .claude/skills/scaffold-act-app/monorepo-template.md:22 — the template a scaffolded user app declares (node >=22.18.0, pnpm >=10.32.1). Different audience and a different decision from this repo's own floor, so out of scope here. Worth a look separately though: a generated app declaring node >=22.18.0 permits a Node that @rotorsoft/act (>=22.23.2) does not, which is a latent inconsistency rather than an immediate break.

Note on the guard

Nothing verifies these values — check:readmes checks section presence, not content. This is the same gap #1650 records for documented export names. Not addressed here; flagging it since it is why both drifted.

Gates

Lint and typecheck clean (run serially — running four pnpm gates concurrently races an esbuild postinstall in this environment, which is not a repo fault). Full suite: 238 files, 3719 passed, 54 skipped.

pnpm check:readmes reports one failure, libs/act-sse: README.md missing — pre-existing and not from this change. libs/act-sse/ is an untracked local leftover containing only dist/ and node_modules/ from the removed package; it is absent from git, so a clean CI checkout is unaffected. Confirmed by stashing this branch's changes and re-running on master, where it fails identically.

Docs only — no book note, no charter surface, no code touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QPx2Qu7ZHDTSpoWYJvX4RJ

The pnpm 12 / vitest 5 upgrade raised the enforced floor and left the
docs behind. CLAUDE.md and intro.md still told a contributor to install
Node 22.23.1 and pnpm 11.9.0, while root engines require >=22.23.2 and
>=12.3.3 — following either one hard-fails at install.

The stale-reference grep turned up the same error on a second surface:
every lib README's Compatibility section understates its own package's
engines.node, nine at >=22.18.0 and act-pg at >=22.23.1, where all ten
declare >=22.23.2. That is a published claim about what a consumer
needs, so it is wrong for readers of the package rather than just for
contributors.

Left alone deliberately: the versioned 1.x docs, which describe what the
released line required, and act-pg's PERFORMANCE.md, which records the
Node a past benchmark actually ran on.

Closes #1651

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPx2Qu7ZHDTSpoWYJvX4RJ
@Rotorsoft Rotorsoft added the bug Something isn't working label Sep 9, 2026
@Rotorsoft Rotorsoft self-assigned this Sep 9, 2026
@Rotorsoft
Rotorsoft merged commit 02de844 into master Sep 9, 2026
16 checks passed
@Rotorsoft
Rotorsoft deleted the act-1651-toolchain-floor branch September 9, 2026 13:27
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown

🎉 This PR is included in version @rotorsoft/act-diagram-v1.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working released

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLAUDE.md and intro.md still document the pre-upgrade Node/pnpm floor

1 participant