build!: move to Node 24 and TypeScript 7

[mrafnadeem-apimatic]

Raises the engine floor to Node 24 and moves compilation to TypeScript 7, ahead of the next major.

Why Node 24

Not because Node 24 is newest — because we should not ship against a runtime that reaches end of life inside this major's supported life. Node 22 is EOL 2027-04-30; Node 24 is patched until 2028-04-30. That is the claim that survives a security questionnaire, and it is the reason worth quoting.

Two things to keep in view:

• Node 22 is still supported upstream for another seven months, so this does lock out anyone standardised on it. That is deliberate — a major is where a floor moves — but it is a real cost, not a free one.
• Node 24 enters maintenance on 2026-10-20 and Node 26 becomes LTS on 2026-10-28, both about five weeks out. The floor is the minimum we support, not what we recommend; 26 is what most developers will be running, which is why CI now tests both.

Why TypeScript 7, and why TypeScript 6 is still here

Measured on this repo, cold, Windows, Node 24.12.0:

Gate	TS 5.9.3	TS 7.0.2
build (full emit)	4939 / 4749 / 4534 ms	1288 / 1258 / 1308 ms	~3.7×
pretest (type-check suite)	4734 / 4835 ms	944 / 1078 ms	~4.7×

The two type-checking gates drop from ~9.5 s to ~2.3 s. To be precise about the claim: pnpm test runs mocha through tsx/esbuild and never touches the compiler, so the mocha run itself is not faster — the win is build and pretest.

@typescript-eslint cannot run on TypeScript 7. Every published version, canary included, declares typescript >=4.8.4 <6.1.0 and throws at module init, which would take out lint, posttest and the pre-commit hook (#10940). So the two compilers sit side by side in Microsoft's documented arrangement: tsc is TypeScript 7 and builds; bare typescript is the TypeScript 6 shim that only the linter loads. Naming them this way, rather than aliasing TypeScript 7, keeps the compiler each script gets written down and survives pnpm update --latest. This is temporary — .ai/instructions.md records the removal steps and the two traps while it stands.

Emitted output was diffed between compilers: 432 files, 81 differ, all cosmetic — sourcemaps, temp-variable naming, declaration ordering, one quote-style change. No semantic change to shipped runtime behaviour.

Notable

• A latent bug surfaced and is fixed (1be71d9). SdkQuickstartAction built its ValidationService from this.configDir in a property initialiser, but configDir is a constructor parameter property. It only worked because downlevel emit assigns parameter properties first; under the native class-field semantics an ES2024 target selects, this.configDir is undefined there. Worth reviewing on its own.
• target moves es2017 → es2024, which also selects native class-field semantics. That is a behavioural change beyond syntax; the suite (480 passing) is the evidence. useDefineForClassFields: false is the one-line fallback if you would rather split it out.
• The portal-only Node gate is gone. It existed for a TanStack Start build requirement, not a CLI-wide one; two gates holding the same number drift. engines is only advisory, so the floor is enforced at run time by an init hook, with a test asserting the constant matches engines.node.
• Releasing on Node 24 removed the npm install -g npm@latest step — Node 22 bundles npm 10.9.8, below the 11.5.1 OIDC publishing needs; Node 24 bundles 11.19.0. The constraint is now a comment on the matrix, because pinning that job back would break publishing silently.
• @types/node is pinned to 24.13.4, not 24.13.6 — newer releases are inside the repo's own 7-day minimumReleaseAge window, and bypassing a supply-chain defence for a types bump is not a trade worth making.

Deviating from what was agreed

The standalone pnpm in test.yml is kept, not reverted to corepack. Its original reason (pnpm 11 needs Node 22.13, the floor was 22.12) is gone, but it is a SHA-pinned executable needing no Node of its own, where corepack resolves pnpm from the registry at run time and needs the three-step setup-node dance. Reverting would have cost supply-chain hygiene in the most security-relevant workflow to remove one step. The comment now states the reason that actually holds. Happy to do the full revert if you disagree.

Verification

pnpm install --frozen-lockfile, pnpm build, pretest, 480 passing / 14 pending / 0 failing, lint clean, built CLI runs, and the engine guard was exercised on both paths.

Lint was run scoped rather than via pnpm test: posttest is eslint ., which also sweeps a stale .claude/worktrees copy in my working tree. CI checkouts do not have that, so CI is unaffected — but it does mean pnpm test fails locally for anyone with a worktree. Not fixed here; say the word and I will add .claude to the eslint ignores.

BREAKING CHANGE: engines.node is now >=24.0.0. Node 22 is no longer supported.

🤖 Generated with Claude Code

[saeedjamshaid]

Review: Node 24 + TypeScript 7 migration

13 findings, 12 of them left inline. The CI ones are the real blockers — the Node 26 leg of check_build cannot work as written, and release.yml is a ticking version of the same bug.

Blocking

1. check_build.yml bumped to Node 26 but still bootstraps pnpm with corepack enable — Corepack is no longer distributed with Node 25+.
2. release.yml has the same corepack bootstrap, plus it pulls pnpm from the registry at release time.
3. The comment justifying the removal of npm install -g npm@latest is factually wrong: the OIDC floor is Node 24.5, not 24.0.

Worth checking before merge
4. Renaming the matrix values renames every reported status check (ubuntu-latest / Node 22.12, Node 22 sample). If branch protection on dev/main requires those names, subsequent PRs will hang on checks that can no longer report — and the fix is in repo settings, not this diff.

One finding that has no line in the diff:

test/mocha.opts survived the ts-node removal. Its first line is --require ts-node/register, naming a package that no longer installs, and its --timeout 5000 contradicts the real --timeout 99999. The file is already dead (mocha dropped mocha.opts support in v8; this repo is on mocha 11 and passes flags on the command line), but it should have been deleted in the same commit that dropped ts-node and the "ts-node": { "esm": true } block from tsconfig.json.

The rest are inline, labelled Blocking / Should fix / Nit.

---

🤖 Review by Claude Code

[saeedjamshaid]

Second pass: is the change justified, and what are the risks?

Following up on the line-level review with a look at the premise rather than the diff. I verified the load-bearing claims rather than taking the description at its word; where I could not, I say so.

Is it justified?

The Node 24 floor: yes, clearly. The reasoning holds up — Node 22 is EOL 2027-04-30, inside the supported life of the major being cut. And this is not a major invented to carry the change: release.config.cjs:12-14 already lists a 1.x branch "once 2.0.0 prereleases exist", so a v2 was planned independently. A floor bump is exactly what a major is for.

TypeScript 7: justified, but it is the weaker half and it carries all the complexity. Two things worth putting on the record, both checked against the registry today:

• TS 7.0.2 is the latest dist-tag, published 2026-07-08 — GA, roughly 2.5 months old, not a preview. That is a much better footing than "native compiler rewrite" suggests on its face.
• @typescript-eslint/parser@8.70.1, the current latest, still declares typescript >=4.8.4 <6.1.0. So the dual-compiler arrangement is genuinely forced, not a stylistic preference. The PR's account of #10940 is accurate.

The framing I would add: these two changes have very different profiles. The floor is high-justification, low-risk and time-sensitive. TypeScript 7 buys roughly 7 s per build/type-check cycle — real developer experience, but no security or user-facing benefit — at the cost of carrying an inverted-name two-compiler setup for an unbounded period, gated on a third party with no ship date. Bundled, the TypeScript 7 decision inherits the floor's urgency.

The counterargument is decent: es2017 → es2024 is itself a semantics change that belongs in a major, and doing it once beats doing it twice. My read is keep it, but decide deliberately — d6ff5d8c is cleanly separable if the team would rather not carry the arrangement yet.

Risks

1. Class-field semantics — verified clean. This is the scariest part of the PR, so rather than trust the suite I walked the AST of both branches looking for eager field initialisers that read a constructor parameter property:

• dev: exactly one hit — src/actions/sdk/quickstart.ts:29 — precisely the bug adb9a3cd fixes.
• this branch: zero.

The five execute arrow-function fields are lazy (the body evaluates at call time, long after the constructor), so they are safe. The three language fields in the event subclasses are constructor-assigned with no base-class accessor to shadow. The claim checks out, and there are no other instances of the pattern. Scope of that check: src/ only, that pattern plus declared-but-unassigned subclass fields. The repo uses no decorators, so the third useDefineForClassFields hazard does not apply.

2. The 1.x maintenance branch does not exist yet. git ls-remote --heads origin returns only beta, dev and main. Published latest is 1.5.0. release.config.cjs and release.yml both already reference 1.x, but once main advances to 2.0.0 there is no correct commit left to branch v1 maintenance from without surgery. main is still on v1 today, so cut 1.x from main before this progresses toward a release branch. This is the most actionable risk outside the CI blockers.

3. Nothing publishes on merge — there is room to sequence. The base is dev, which is not in release.yml's trigger list (alpha, beta, main, 1.x). The 2.0.0 cut happens later, when dev reaches a release branch. That is what makes point 2 sequenceable rather than urgent.

4. The inverted names are protected only by documentation. typescript resolves to TypeScript 6; the tsc binary is TypeScript 7. Anyone reasoning "the typescript dependency is the compiler" is wrong, and pnpm outdated lists both under the real name. Worth a CI assertion — tsc --version starts with 7, the typescript package resolves to 6 — so that a bad pnpm update fails loudly instead of silently swapping compilers. Documentation is the right place to explain the arrangement, but the wrong place to enforce it.

5. The emit diff is the load-bearing claim, and it is not reproducible from the PR. "432 files, 81 differ, all cosmetic" is the entire basis for no semantic change to shipped runtime behaviour, and it rests on one local run recorded in prose. I could not reproduce it. If that claim matters — and for a compiler swap that emits the published artefact, it should — it belongs in CI or attached as an artefact rather than as a sentence in the description.

6. Declaration emit reaches consumers. tsconfig.json sets declaration: true and the package ships types: lib/index.d.ts. Almost certainly vestigial oclif scaffolding for a bin-only package — but if anything imports @apimatic/cli as a library, TypeScript 7's declaration emit is in the blast radius. Worth confirming whether types should simply be dropped.

7. The floor lands on merge, not at release. The new init hook hard-exits on anything below Node 24, so any contributor still on Node 22 or 23 is blocked from running the built CLI from the day this merges — well before 2.0.0 ships. Intended behaviour, but it is worth an explicit heads-up to the team rather than letting people discover it as a crash.

8. .claude is missing from the eslint ignores — confirmed. eslint.config.js:52-62 ignores lib, node_modules, portal-template, tmp and the test-* directories, but not .claude. Claude Code creates worktrees under .claude/worktrees by default, so posttest (eslint .) will sweep them and pnpm test will fail locally for anyone who uses one. The PR offers the one-line fix — worth taking.

9. Scope. Nine commits spanning engine floor, compiler swap, a latent runtime bug fix, CI matrix, VS Code config, .gitignore, mock-fs removal and docs. The mock-fs removal is a genuine prerequisite (Node 26.8's fs rewrite breaks its binding interception, and CI now tests 26), not creep. But adb9a3cd is a real runtime bug fix that deserves its own review attention — exactly the kind of change that gets waved through inside a large build PR. The description flags it, which is the right instinct.

Bottom line

Justified, and the engineering is better than the average migration PR. The description is unusually self-critical, and the one claim verifiable end-to-end — the class-field hazard — held up exactly. The blockers are the three CI findings in the line-level review, not the premise.

• Before merge: fix the corepack and OIDC-floor issues, cut 1.x from main, add .claude to the eslint ignores.
• Before release: get the emit-diff check into CI, or accept it explicitly as a one-time attestation.

---

🤖 Review by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.6% Duplication on New Code

See analysis details on SonarQube Cloud

[saeedjamshaid]

Re-review at a404e3f

All thirteen findings from the first pass are addressed, and all ten checks are green including the full six-cell matrix. Notes on what I verified rather than took on trust:

• The engine guard now reads the manifest. this.config.pjson.engines?.node + semver.satisfies closes both the mirrored-constant and major-only-comparison findings in one change, and the three new tests exercise the outside-range, inside-range and no-engines paths for real. semver is in dependencies, not devDependencies — correct, since the init hook imports it at runtime in the published package.
• The template-floor test is a better answer than the constant I suggested. Asserting engines.node is a semver.subset of every template dependency's declared range keeps the fact on record and checks it. I resolved all sixteen TEMPLATE_DEPENDENCIES against the installed tree: every range is open-ended upward (>=20.19, >=22.12.0, ^20.19.0 || >=22.12.0, >=20, >=0.10.0), so the assertion holds across the board today.
• Both workflows are correct. Standalone pnpm ordered before setup-node, single node step, cache: 'pnpm' and cache-dependency-path retained.
• Formatting is clean. No line over 120 characters in any changed file.
• test/mocha.opts and .vscode/launch.json are both gone, .gitignore re-ignores the latter, and .ai/instructions.md now names the e2e call site.

Four new points on the five new commits, none of them blocking. The only substantive one is the preview-server bind.

Still outstanding outside this PR, for whoever has admin: cut 1.x from main while it is still on v1, and preserve the BREAKING CHANGE: footer when squashing — the repo's squash_merge_commit_message is COMMIT_MESSAGES so it is there by default, but trimming it turns a build type into no release at all rather than 2.0.0.

---

🤖 Review by Claude Code

[saeedjamshaid]

Worth a second look — this pins the bind to IPv4, but the fetch target is still localhost, resolved inside TanStack Start. The two ends can still disagree.

On a host where localhost resolves only to ::1 — IPv6-only containers being the realistic case — the prerender fetch can now never reach the server, which is the exact inverse of the failure this fixes. What saves the common case is autoSelectFamily (default true on Node 20+) falling back to IPv4, so in practice this is very likely net-positive. But the mismatch is still there; it is just biased the other way now.

If TanStack Start exposes the prerender origin, pinning both ends to 127.0.0.1 would make it deterministic rather than dependent on Happy Eyeballs. If it does not, worth saying so in the comment — "binding IPv4 leaves the fetch a single address to reach" reads as though the fetch is constrained too, and it is not.

Separately: the trigger described ("a connect that stalls under load") is a flake, and there is no link to the run that caught it. The e2e does have real coverage here — test.yml:51 sets APIMATIC_E2E: '1' across all six cells — so a run URL in the commit body would let the next person tell whether it recurred or whether this fixed it.

[saeedjamshaid]

Nit — worth a note in the test. semver.subset against an open-ended supported range has a sharp edge: the moment any template dependency adopts a capped range (^20 || ^22 || ^24 is a common shape), this flips to false and CI goes red.

That is arguably the test doing its job — CI tests Node 26, so a capped dependency genuinely is news. The trap is that the obvious way to make it green again is capping engines.node to match, which is usually the wrong call. A line saying what to do when it fires (check whether the cap is real, and prefer waiting for a dependency release over narrowing the CLI's own range) would save the next person that decision.

For the record, I resolved all sixteen entries against the installed tree and every declared range is open-ended upward today, so nothing is close to tripping it.

[saeedjamshaid]

Nit — readManifest('.') and path.join('node_modules', dependency) below are resolved against the current working directory, while every other test in this file builds absolute paths from os.tmpdir(). It works because mocha runs from the repo root, but it is the one test here that would break if that ever stopped being true.

There is also a subtler mismatch: this reads the top-level node_modules/<dep> entry, whereas runtimeProblem() resolves the same dependency through createRequire from the installed CLI. Under this pnpm layout they land on the same package, but they are different resolution mechanisms, so the test can in principle assert against a different copy than the code under test uses.

[saeedjamshaid]

Nit — the pnpm action just above is SHA-pinned, but actions/checkout@v4 and actions/setup-node@v4 in this same job are still floating tags. Given the stated rationale for standalone pnpm was supply-chain hygiene specifically in the publishing workflow, the inconsistency stands out.

These are GitHub-owned actions and a v4 tag is a much smaller exposure than a registry fetch, so this is genuinely minor — but if the pinning is worth doing here, it is worth doing to all three.

[github-actions]

🎉 This PR is included in version 2.0.0-beta.1 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀