[X-Guardian]

Description

Migrates the monorepo's package manager from Yarn (Classic / v1) to pnpm. The version is pinned via package.json#packageManager and activated through corepack, so there is no separately installed pnpm to keep in sync. No runtime/library behaviour changes — this is build-, CI-, and dependency-tooling only.

Why pnpm: stricter, non-hoisted node_modules (a package can only import what it declares), a content-addressed store (faster, less disk), and first-class workspace support. The strictness is the point — it surfaces undeclared-dependency bugs that Yarn's flat hoisting silently tolerated (see the punycode and bin notes below). Also v11 has supply chain protection on by default; package installs minimumReleaseAge set to 1 day.

Core migration:

• Lockfiles & workspace config: removed yarn.lock (root, test/, tools/documentation-generation/) and .yarnrc.yml; added pnpm-lock.yaml and pnpm-workspace.yaml. The workspace lists packages/*, packages/@cdktn/*, examples/**, and tools/generate-function-bindings, plus onlyBuiltDependencies (allow-list for postinstall builds) and overrides (@types/react, jsii).
• test/ is a standalone pnpm project, not a workspace member — its own pnpm-workspace.yaml makes it a self-contained workspace root, so pnpm's upward discovery stops there and never pulls in the repo root. This matches how the integration suite publishes packages to a local Verdaccio registry and installs them as a consumer would. Note: test/ installs without --ignore-workspace — that flag discards the local pnpm-workspace.yaml (including its allowBuilds), which under pnpm 11 then fails with ERR_PNPM_IGNORED_BUILDS for the unrs-resolver build script. The local workspace file already provides the isolation, so the flag was both redundant and harmful.
• Workspace dependencies switched from 0.0.0 to workspace:* across the @cdktn/* packages.
• Scripts & package manager refs: yarn … → pnpm … / pnpm exec … across root and package scripts, package.sh files (npm pack → pnpm pack | tail -n 1), and link-packages/integration:* scripts.
• CI: every workflow now runs actions/setup-node + a new composite action .github/actions/setup-corepack-pnpm (enables corepack, activates the pinned pnpm, caches the corepack binary and the pnpm store) before pnpm ci. Yarn caches removed.
• HUSKY: "0" set on every CI workflow. The root prepare script is husky (installs git hooks), and pnpm runs prepare on install. In CI that's pointless and fragile (no commits happen, and hook install can fail in the container/checkout state), so the env var disables it.

Non-obvious changes the strictness forced (each surfaced as a CI failure and fixed):

1. cdktn-cli bin decoupled from build output. The bin field pointed at bundle/bin/cdktn, which only exists after a build. pnpm validates bin targets when linking workspace packages, so this broke install. Added a committed bin/cdktn launcher (require("../bundle/bin/cdktn.js")), repointed the bin field, deleted src/bin/cdktn and its build-time copy step, and made the CLI tests resolve the bin from package.json rather than hardcoding the path. The build config now compiles to a gitignored build-config/ dir.
2. punycode declared in cdktn-cli. build.ts aliases punycode → punycode/ (userland package, to dodge Node's deprecated builtin). pnpm doesn't expose this undeclared transitive to cdktn-cli, so the esbuild alias couldn't resolve. Declared punycode as a direct dependency; added it to knip's ignoreDependencies (it's referenced only via the alias string, which knip can't trace).
3. Other undeclared dependencies declared. Same root cause as punycode — packages used transitives that Yarn's hoisting exposed but pnpm doesn't. Added the missing direct deps where they're actually imported, e.g. @types/fs-extra in @cdktn/hcl-tools, @types/cross-spawn + cross-spawn in test/, and assorted @types/* (babel__generator, babel__template, minimatch).
4. Provider-generator dep resolution made static. In constructs-maker.ts and the edge-schema test cli.ts, the jsii compile-against deps were built by mapping over a ["@types/node", "constructs", "cdktn"] array through require.resolve(${dep}/package.json). Rewrote them as explicit require.resolve("constructs/package.json") calls (one per dep) so both knip and pnpm's strict isolation can see the dependency edges. Also added { dereference: true } to the jsii output fs.copy so pnpm's symlinked node_modules are materialised as real files rather than copied as dangling links.
5. New packages/cdktn/scripts/pack.mjs. cdktn bundles runtime deps (json-stable-stringify, semver, yazl) into its published tarball so jsii-pacmak can embed them in the Python/Java/Go/.NET targets. Under pnpm's symlinked layout, npm pack (invoked by pacmak) follows the symlinks into .pnpm/ and emits ..-escape tarball paths that extractors drop — leaving the bundled deps' transitives missing. The script stages cdktn's source into a temp dir, runs npm install --omit=dev there to get a real nested node_modules, then runs jsii-pacmak against the staging dir and copies dist/ back. Replaces the previous inline packaging.
6. Testing.fakeCdktfJsonPath fixture path. Changed cdktfRelativeModules from ["./"] to ["./test/fixtures/"] so the test no longer scans the whole package root — under pnpm's layout ./ pulled in symlinked workspace content and broke the fixture's module resolution.

Checklist

• I have updated the PR title to match CDKTN's style guide
• I have run the linter on my code locally
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation if applicable
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works if applicable
• New and existing unit tests pass locally with my changes

[sakul-learning]

I reviewed the latest head (4ddb8b8f) for the pnpm migration.

I also reran the relevant package/build/test commands through pnpm locally, and the direct package build/test path for cdktn passed.

Things that look good:

• The configured package/build/test path runs successfully with pnpm.
• The shared pnpm setup action is a good direction for keeping workflow setup consistent and cacheable.

Issues to address before merge:

1. The release prepare-next job appears to use pnpm before setting pnpm up.

   Other release jobs use the new shared pnpm setup action before installing dependencies, but prepare-next goes straight from Node setup to pnpm ci. On a fresh runner/container this can fail with pnpm: command not found or use an unexpected corepack/pnpm state.

   Suggested fix: add the same shared pnpm setup step used by the other release jobs before dependency installation in prepare-next.

2. One reusable workflow command appears to be using invalid Nx syntax.

   The command pattern using nx run --scope <package> build fails locally. The equivalent target form, nx run <package>:build, succeeds. The PR checks are green, so this looks like a latent workflow/release-path issue rather than a currently failing PR unit-test issue.

   This is also the new PR-specific workflow security finding from zizmor: the package input is interpolated directly into a shell command. Prefer validating/allowlisting the input and passing it through env: before using it in shell.

3. Minor cleanup: a few user-facing references still mention Yarn.

   Examples:

   • CLAUDE.md still says yarn nx test --watch is the recommended dev loop, immediately after the surrounding examples were migrated to pnpm.
   • test/run-against-dist still prints messages telling users to run yarn run package / yarn run package:$lang when dist outputs are missing.

   These are not blockers, but they would be confusing after this migration lands. The remaining examples/diagnostics should be updated to pnpm.

Security scan note:

• I ran zizmor against the workflows/actions and compared the PR head with the existing baseline.
• Most findings are pre-existing workflow hardening concerns, not regressions introduced by this PR.
• I created a separate tracking issue for the broader tech debt/security-hardening work, especially cache-poisoning and workflow-permission concerns: Track GitHub Actions workflow security hardening #247

Overall: the pnpm migration itself is in good shape and the PR checks are green, but I would still fix the two workflow issues above before merging because they affect release/reusable workflow paths that the PR checks do not fully exercise.

[jsteinich]

I did a check for existing mentions of yarn and found a few remaining pieces:

1. Referenced in CLAUDE.md and run-against-dist - we should just clean these up now
2. The dependency pinner tool - can just remove the entire tool in a follow-up PR
3. NodePackageManager - we should probably support pnpm in the cli given that we are switching to it. Can be done a follow-up PR

Other pieces noticed:

• The prepare-next job in release.yml is missing the corepack pnpm setup
• The lint job in quality.yml has 2 setup-node steps (may have already been there, so not critical)
• nx run --scope <package> build that was added to the unit-test job in unit.yml seems unnecessary
• The TypeScript examples are a bit of a mixed story. The help says to run npm commands, but the packages are setup for pnpm workspaces. While that's nice for ci / cdktn developers, it's confusing for end users looking at the examples. They are meant for end users, so we should make sure they are presented consistently even if that means an extra step in ci.

[X-Guardian]

I've resolved all the review comments.

The typescript examples are no more or less inconsistent than they were before. i.e. a mix of pnpm and npm vs yarn and npm.

[jsteinich]

The typescript examples are no more or less inconsistent than they were before. i.e. a mix of pnpm and npm vs yarn and npm.

While I mostly agree with that, there is a small regression.

Previously when running npm install in an exampled you'd get:

npm error notarget: No matching version found for cdktn@0.0.0.

Now you get:

npm error Unsupported URL Type "workspace:": workspace:*

Ideally it would just work, but that's more of a separate issue.

The error message in the first case is much more clear what is wrong. As there's a lot here, I can see the value in merging as is and following up on that, but if there's an easy way to resolve, I'd like to see that.

[X-Guardian]

We can have a pre-processing script on the examples integration tests workflow that replaces the package.json properties in the examples with what is needed to run the tests, but lets do that in another PR.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.