Skip to content

fix: align the workspace Node runtime floor - #72

Open
VeraPyuyi wants to merge 1 commit into
LodyAI:mainfrom
VeraPyuyi:fix/root-node-runtime-floor
Open

fix: align the workspace Node runtime floor#72
VeraPyuyi wants to merge 1 commit into
LodyAI:mainfrom
VeraPyuyi:fix/root-node-runtime-floor

Conversation

@VeraPyuyi

@VeraPyuyi VeraPyuyi commented Aug 27, 2026

Copy link
Copy Markdown

Related issue

Closes #116

Problem / pressure

The SQLite binding requires Node-API 10. The workspace admitted Node 22.0-22.13 and the simple >=22.14.0 range also admits Node 23.0-23.5, although Node-API 10 starts at 22.14.0 and 23.6.0. The pinned pnpm 10.20 additionally does not enforce devEngines.runtime.onFail: error, so unsupported installs could continue after warnings; newer global pnpm versions could also bypass the legacy packageManager pin.

Summary

  • Align root, CLI, and turn-diff-store engine ranges to >=22.14.0 <23 || >=23.6.0.
  • Add a package-manager-independent preinstall check that fails closed when process.versions.napi is below 10.
  • Enforce the exact pnpm 10.20.0 workspace version through engines.pnpm, while retaining the existing Corepack pin.
  • Keep root engines, devEngines, both SQLite-owning package manifests, contributor guidance, and runtime diagnostics aligned.
  • Extend regression coverage to compare all three manifests and exercise the hard preinstall failure path.

PR #60 has merged. A reviewed follow-up that aligns its quickstart wording with the exact Node 22.14-22.x or 23.6+ boundary remains local until issue #116 receives maintainer agreement.

Before / after

Before After
Workspace tooling and one SQLite-owning package admitted early Node 22 or unsafe early Node 23 releases. Manifests express the exact Node-API 10 boundary, preinstall enforces it independently of pnpm's devEngines bug, and mismatched pnpm versions stop before dependency resolution.

Test plan

  • corepack pnpm --dir apps/cli exec vitest run tests/sqlite-runtime-support.test.ts tests/native-sqlite-install-free.test.ts (11 passed)
  • corepack pnpm --dir apps/cli typecheck
  • corepack pnpm --dir packages/turn-diff-store test (31 passed)
  • corepack pnpm --dir packages/turn-diff-store typecheck
  • corepack pnpm exec oxlint --type-aware apps/cli/src/utils/sqlite-runtime-support.ts apps/cli/tests/sqlite-runtime-support.test.ts scripts/check-node-runtime.mjs (0 warnings/errors)
  • corepack pnpm exec prettier --check on all changed files
  • Real Node.js 22.13.1 / Node-API 9 check exits 1 with the expected diagnostic; current Node-API 10 exits 0
  • Plain pnpm 11.19.0 is rejected by engines.pnpm; corepack pnpm resolves the pinned 10.20.0
  • corepack pnpm lint:i18n
  • corepack pnpm check:code-collab-imports
  • corepack pnpm check:platform-boundaries
  • corepack pnpm check:public-boundary
  • Root/CLI manifest parse and exact-range check; git diff --check origin/main...HEAD

Context handoff

Instructions for reviewing agents

  • Review focus: Verify the Node-API 10 semver boundaries, root/CLI/turn-diff-store manifest equality, exact pnpm enforcement, direct-execution preinstall guard, test isolation, and contributor wording.
  • Decisions to challenge: Confirm that a lightweight preinstall check is the appropriate compatibility fallback for pinned pnpm 10.20 ignoring devEngines.runtime.onFail: error.
  • Plausible failures / evidence gaps: The exact cross-major quickstart wording is prepared locally but has not been pushed; future Node majors were not individually executed, while the runtime guard checks the actual Node-API level.

Authoring context

  • User goal / directives: Contribute a focused SQLite runtime compatibility fix with tests and independent review before publishing follow-up commits.
  • Constraints / non-goals: Keep this separate from the Windows encoding change, avoid a pnpm upgrade or lockfile rewrite, and follow the current maintainer-approval policy.
  • Risk-bearing decisions: Express the exact 22.14/23.6 boundary in all three manifests, fail workspace installation based on Node-API level, and reject pnpm versions other than the repository's existing 10.20.0 pin.
  • Destructive or irreversible behavior: Unsupported runtimes stop before dependency installation; no user data or repository state is migrated or deleted.
  • Deliberately not done or tested: Future Node majors were not each run locally; unrelated repository-wide Windows baseline failures were not changed.
  • Unknowns / confidence: Manifest and runtime behavior are covered, but maintainer agreement on issue [Bug] Root workspace admits Node runtimes below the SQLite compatibility floor #116 is still pending and the reviewed follow-up commit remains local until that gate is satisfied.

Keep root runtime declarations and contributor guidance aligned with the Node-API 10 floor already enforced by the CLI SQLite guard.

Model: GPT-5
@VeraPyuyi

Copy link
Copy Markdown
Author

This PR predates the contribution-intake policy introduced in #91. I opened #116 with the reproduction and proposed scope, and I am waiting for explicit maintainer agreement before updating the branch or converting the body to the current template.

The prepared follow-up also resolves the post-#60 documentation gap: 22.14 or later incorrectly includes Node 23.0-23.5, so the English/Chinese quickstarts, tracked compatibility asset, contributor guidance, and runtime diagnostics now consistently say Node.js 22.14-22.x or 23.6+ (Node-API 10+).

Prepared validation: CLI runtime tests 12/12 passed, turn-diff-store tests 31/31 passed, both typechecks passed, type-aware lint and code formatting passed, docs generation passed, repository boundary checks passed, and git diff --check passed. I will push the reviewed follow-up and update the PR body after a maintainer confirms #116.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Root workspace admits Node runtimes below the SQLite compatibility floor

1 participant