chore: migrate from npm to pnpm with supply chain hardening

[Kabidoye-17]

Why?

This repo was surfaced in a follow-up audit as part of the org-wide effort to bring active npm repos onto a supply-chain-hardened footing (per-package script gating, install cooldown, pnpm's stricter dependency graph). Migrating to pnpm 10 aligns Intercom-OpenAPI with the target config already applied across the sibling repos in FE-3214.

How?

pnpm import was used to convert package-lock.json to pnpm-lock.yaml verbatim, preserving every resolved version so no transitive dependency drift shipped alongside the tooling swap. Supply-chain settings (minimumReleaseAge: 10080, trustPolicy: no-downgrade) live in pnpm-workspace.yaml; the es5-ext cosmetic postinstall is silenced via pnpm.ignoredBuiltDependencies. Registry-source lockdown is already handled at the infra layer by Socket Firewall, so no pnpm-side config is needed here. Disabled workflows under .github/workflows-disabled/ were updated so they continue to work if re-enabled — the new pnpm/action-setup refs are SHA-pinned. Pre-existing GHA hardening gaps (unpinned actions/checkout, missing top-level permissions: blocks) were left out of scope; whoever re-enables any workflow should run the security-review skill end-to-end first.

Follow-up

fern-api is pinned to 5.65.3 in workflows. pnpm add -g fern-api (unpinned) fails through Intercom's registry proxy because the proxy serves the fern-api manifest without a dist-tags block, and pnpm has no fallback resolver for a missing latest tag. Upstream issues, both open:

• pnpm/pnpm#5564
• pnpm/pnpm#9944

When those are fixed (or the proxy is fixed to include dist-tags), the pin can be dropped.

_{Generated with Claude Code}

[Kabidoye-17]

Local Verification — no regressions

Same fern flow run on both sides. The same 3 pre-existing spec errors and 295 warnings appear on main and on this branch — no new errors introduced by the migration.

Master (npm install)

rm -rf node_modules && npm install — 550 packages in 6s; 6 deprecation warnings; 12 vulnerabilities (4 moderate, 8 high) reported by npm audit.

npm install -g fern-api → fern check → fern generate --preview --group ts-sdk — 3 errors, 295 warnings.

This branch (pnpm install)

rm -rf node_modules && pnpm install — 522 packages in 3.3s; preinstall guard runs and exits 0. The ${GITHUB_TOKEN} .npmrc warning is pre-existing (harmless — no @intercom/* runtime deps consume it).

fern check — 3 errors, 295 warnings (identical to master).

fern generate --preview --group ts-sdk — 3 errors, 295 warnings (identical to master).

Errors — identical on both sides

File	Error
preview/conversationsAttributes.yml	CreateConversationAttributeOptionRequest already declared in preview/__package__.yml
preview/articles.yml	PublishArticleDraftRequest already declared in preview/__package__.yml
preview/articles.yml	UpdateArticleRequestBody is not defined

Pre-existing spec issues, unrelated to the migration.

~ Automated via Claude

[shrek-intercom]

❌ PR Review Summary: NEEDS HUMAN REVIEW

	Summary
✅	🎯 Problem — The PR title and description are excellent, clearly articulating the motivation (org-wide supply chain hardening audit), referencing the broader initiative (FE-3214), and documenting key implementation decisions and follow-up considerations.
✅	📝 Alignment — All substantive claims in the description are confirmed by the diff, including the npm-to-pnpm migration, supply-chain settings in pnpm-workspace.yaml, es5-ext silencing, SHA-pinned pnpm/action-setup in disabled workflows, fern-api pinned to 5.65.3, and explicitly scoped-out GHA hardening gaps.
ℹ️	🧠 Correctness — Disabled for this repository.
❌	🦺 Safety — The PR touches multiple categories requiring mandatory human review: seven CI/CD workflow files under .github/, dependency manifests and lockfiles (package.json modified, package-lock.json deleted, pnpm-lock.yaml and pnpm-workspace.yaml added), and the sensitive CLAUDE.md configuration file.
❌	🚦 Auto-approval — Touches AI config files (CLAUDE.md); Exceeds LOC limit (10800 meaningful LOC > 150, raw 10800)

Per-criterion details

Problem

Excellent PR description that clearly explains the why (org-wide supply chain hardening audit), provides context about the broader initiative (FE-3214), and documents important follow-up considerations. While the How section is detailed, it's justified for a security-related infrastructure change where implementation decisions matter.

Alignment

The PR description claims a migration from npm to pnpm with supply chain hardening. Checking each claim against the diff:

1. npm to pnpm migration: ✅ The diff shows package-lock.json deleted, pnpm-lock.yaml created, package.json updated with "packageManager": "pnpm@10.23.0", all workflow files changed from npm install -g fern-api to pnpm add -g fern-api@5.65.3, and documentation (CLAUDE.md, CONTRIBUTING.md) updated with pnpm commands.

2. Supply-chain settings (minimumReleaseAge: 10080, trustPolicy: no-downgrade) in pnpm-workspace.yaml: ✅ Confirmed exactly in the new pnpm-workspace.yaml file.

3. es5-ext silenced via pnpm.ignoredBuiltDependencies: ✅ Confirmed in the package.json changes.

4. Disabled workflows updated with SHA-pinned pnpm/action-setup: ✅ All 7 workflow files under .github/workflows-disabled/ use pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.1.0.

5. Pre-existing GHA hardening gaps left out of scope: ✅ The diff shows actions/checkout@v4 and @v3 remain unpinned, consistent with the claim.

6. fern-api pinned to 5.65.3: ✅ All workflows use pnpm add -g fern-api@5.65.3.

7. pnpm import used: The diff shows package-lock.json deleted and pnpm-lock.yaml created as new file, consistent with this claim (we can't verify the exact command from the diff alone, but the outcome matches).

No significant changes in the diff are omitted from the description. The CONTRIBUTING.md additions (pnpm setup instructions) are a minor doc update that's implicitly part of the migration. All substantive changes are accurately described.

Safety

This PR is a tooling migration from npm to pnpm that touches multiple categories of files explicitly listed as requiring human review in the safety criteria. The changes include:

1. CI/CD workflow files (.github/workflows-disabled/): Seven workflow files are modified. Even though they're currently in a "disabled" directory, they are under .github/ and represent CI/CD configuration.

2. Dependency manifests and lockfiles: package.json is modified (adding packageManager field and pnpm.ignoredBuiltDependencies), package-lock.json is deleted entirely, and new pnpm-lock.yaml and pnpm-workspace.yaml files are added. These are explicitly called out as unsafe in the criteria.

3. CLAUDE.md: The project instructions file is modified (changing npm install to pnpm install references). The criteria note that "CLAUDE.md and .claude/ config are treated as sensitive."

None of the changes touch the safe categories (Unstable/Preview spec, generated Postman collections, or general documentation like README). While CONTRIBUTING.md changes alone might qualify as safe documentation, the PR as a whole is clearly infrastructure/tooling work that requires human review.

<violated_criteria>
CI/CD and repo config — changes to files under .github/ (seven workflow files in .github/workflows-disabled/ are modified)
Dependency manifests / lockfiles — package.json modified, package-lock.json deleted, new pnpm-lock.yaml and pnpm-workspace.yaml added
CLAUDE.md modification — sensitive project configuration file edited
</violated_criteria>

_{Rate this comment 👍 / 👎 to help us improve 🙏 · Disagree with assessment? Establish ground truth here}

[levindixon]

Reviewed, tested, and verified this locally. All the repo's workflows are disabled so CI can't exercise any of the pnpm path - I ran the migration's claims end-to-end on this branch instead. Everything load-bearing checks out.

No blockers - one should-fix nit, one optional nit, two FYIs below.

What looks good:

• The pnpm import fidelity claim is exactly true: I diffed resolved versions across both lockfiles - 487 packages on each side, zero only-in-one, zero version drift.
• pnpm install --frozen-lockfile is clean on 10.23.0: no unknown-setting warnings (both pnpm-workspace.yaml keys are valid on this version), no build-script prompts, and es5-ext@0.10.64 really is in the tree, so the silencing entry is doing something.
• Every non-builtin require() in scripts/ is a declared dependency, and regenerating the Postman collections for all 9 stable versions worked on the pnpm tree - the stricter node_modules layout doesn't break anything here.
• All 7 workflows run checkout before pnpm/action-setup (required, since with no version input the action reads packageManager from the checked-out package.json), and the action exports PNPM_HOME at the pinned ref, so pnpm add -g fern-api@5.65.3 gets a global bin dir on runners. The pnpm setup note in CONTRIBUTING is correctly scoped to local machines only.

Nit (should fix): the pin comments say # v4.1.0 but b906affcc is v4.3.0. v4.1.0 is a7487c7, and the floating v4 tag currently sits on b906affcc, which is probably how the SHA got resolved. The pin itself is correct and safe - it's just the label that's wrong, and both humans and version-bump tooling (Renovate-style pin updates) read that comment to know what's pinned. 10 occurrences across the 7 workflow files, s/v4.1.0/v4.3.0/ and done.

Nit (optional): the ts job in preview_sdks.yml still has the pre-existing unpinned pnpm/action-setup@v4 at its Compile step. Pre-existing hardening gaps are declared out of scope, but this one is the same action the PR pins everywhere else, and v4 resolves to the same b906affcc commit today, so pinning it is behavior-neutral.

FYI: three lockfile entries will trip trustPolicy: no-downgrade the next time they get re-resolved: semver@5.7.2, semver@6.3.1, undici@5.29.0. I replayed pnpm's check against all 524 pinned versions and each of these is a provenance downgrade vs an earlier release of the same package. Frozen installs don't run the check (verified - that's why CI stays green), so this only bites the first pnpm add / pnpm update that touches one of them. Escape hatch when it does: trustPolicyExclude (supported since 10.22.0), or bump the parent deps.

FYI for whoever re-enables fern_check.yml: fern check currently fails with 3 pre-existing errors in the Preview fern defs (duplicate CreateConversationAttributeOptionRequest / PublishArticleDraftRequest declarations, undefined UpdateArticleRequestBody). Reproduces on main, unrelated to this PR.

Verification detail: what I ran and what it showed

• Lockfile fidelity: parsed both lockfiles and diffed resolved versions. 487 packages each, zero only-in-one, zero version differences.
• pnpm install --frozen-lockfile on pnpm 10.23.0 (matching packageManager): clean in ~3s, 524 packages. No unknown-setting warnings (minimumReleaseAge landed in 10.16.0, trustPolicy in 10.21.0).
• Phantom-dep audit: every non-builtin require() across scripts/ (@actions/core, @stoplight/json-ref-resolver, api, axios, deepmerge, dotenv, jsonpath-plus, lodash, uuid, yaml) is declared in package.json.
• End-to-end: node scripts/postman/generate-postman-in-repo.js regenerates all 9 stable versions on the pnpm tree. Two pre-existing observations, both reproduce on main: the checked-in postman/ outputs are stale (last generated 2026-04-16, the spec has since gained fields like audience_ids), and the Preview (0) version crashes in collection.js's formdata path - that script hasn't changed since 2025-04 and runs identical dep versions, so it's not this PR.
• Workflows: all 7 files run actions/checkout before pnpm/action-setup. generate_postman_collection.yml has the right cache order (action-setup -> setup-node with cache: pnpm -> frozen install). The action at b906affcc exports PNPM_HOME and prepends it to PATH.
• Pinned fern install: npx -y fern-api@5.65.3 check resolves and runs through the registry proxy, consistent with the dist-tags analysis in the description (exact-version resolution doesn't need dist-tags.latest).
• Bonus latent fix: the tracked .npmrc references ${GITHUB_TOKEN}. npm hard-fails on an unresolvable env template and runners don't export that var by default, so the old npm install -g fern-api steps had a latent failure mode. pnpm 10 tolerates the unset var - tested with it explicitly unset.
• Residue sweep: zero references to npm commands or package-lock.json left in docs, workflows, or scripts.

The upstream issue links (pnpm/pnpm#5564, pnpm/pnpm#9944) and the explicit re-enable caveat in the description are exactly the context a future maintainer needs.

~ Automated via Claude