chore(deps): replace lerna with nx (#315)

### Description

The repo already uses nx as its task runner for `test`, `lint`, and the
affected-graph, but still depends on lerna for a handful of
orchestration and release chores. This PR removes lerna entirely and
routes those chores through nx, then converts the touched shell scripts
to ESM Node.

**Lerna → nx command mapping:**

- `lerna run --scope <glob> <target>` → `nx run-many -t <target> -p
<glob>` (root `build`, `package*`, `watch`, `dist-clean` scripts).
- `lerna exec --scope <glob> -- <cmd>` → `nx exec -p <glob> -- <cmd>`
(`link-packages`, and the `ncu` runs in `pnpm-upgrade.yml`).
- `lerna ls -p` (absolute package paths) → `pnpm --recursive exec pwd`.
- `lerna list --all --json` / `lerna ls --all --json` (only the package
**names** were used) → `nx show projects --json`.
- `lerna version <v>` → `nx release version <v>`. This needs a `release`
block in `nx.json` (fixed release group of `cdktn`, `cdktn-cli`,
`@cdktn/*`); the command is run with `--git-commit/tag/push=false
--stage-changes=false` so it only rewrites versions on disk, matching
the old `--no-git-tag-version --no-push` behaviour.

### Other Changes

**Dead code deleted rather than converted** (both were unreferenced —
nothing in the repo or CI invoked them):

- `tools/build-unit-test-matrix.sh` — the unit workflows build their
matrix inline via `nx show projects --affected`; this script was
orphaned.
- `tools/setup-prebuild-provider-folder.sh` — a manual utility that
scaffolded a workspace of cloned `hashicorp/*` provider repos, which are
no longer the canonical source.

**Shell/batch scripts converted to ESM Node** (`.mjs`), per the repo's
preference for JS ESM tooling:

- `tools/align-version.sh` → `tools/align-version.mjs`. Also drops a
dead `jq` loop that rewrote `0.0.0` peerDependencies — the only internal
peerDep is `cdktn: workspace:*`, which jsii-pacmak resolves to a
concrete version at pack time (verified against the built tarball), so
the loop matched nothing.
- `tools/collect-dist.sh` **and** `tools/collect-dist.bat` → a single
cross-platform `tools/collect-dist.mjs` (uses `fs.cpSync(..., {
dereference: true })` for the `rsync -aL` behaviour; verified
byte-identical output to the old script). The `.bat` was still calling
`lerna ls -p`, so this also removes the last stray lerna reference.
`package-windows` now runs the same `.mjs` as every other platform.
- `tools/build-example.js` → `tools/build-example.mjs` (CJS
`require`/`__dirname` → ESM). This leaves no CommonJS in top-level
`tools/`.

**Lint coverage for `tools/`:** the root `eslint.config.mjs` ignores all
`**/*.js` and `**/*.mjs`, and ESLint flat config does not auto-discover
nested config files — so the top-level `tools/` scripts were never
linted (per-project linting only works because nx invokes ESLint per
project). Added `tools/project.json` (`@tools/scripts`) so nx infers a
`lint` target and the scripts are picked up by `nx run-many -t lint`,
plus `tools/eslint.config.mjs` that lints them as plain ESM JavaScript
(no type-aware TS parsing) and defers to the nested `tools/*` projects
for their own files.

**Callers updated:** `release.yml`, `unit.yml`, `pr-unit.yml`,
`examples.yml`, `pnpm-upgrade.yml`, `CONTRIBUTING.md`, and
`docs/release-please.md`. Stale `!tools/*.js` negations in `.gitignore`
/ `.prettierignore` are dropped (the `.mjs` replacements aren't caught
by the `*.js` ignore, so they need no negation).

### Checklist

- [ ] I have updated the PR title to match [CDKTN's style
guide](https://github.com/open-constructs/cdk-terrain/blob/main/CONTRIBUTING.md#pull-requests-1)
- [ ] 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](https://github.com/open-constructs/cdk-terrain-docs/tree/main/content)
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

Co-authored-by: Simon Heather <simon.heather@yulife.com>

Author: X-Guardian

.github/workflows/examples.yml

@@ -164,7 +164,7 @@ jobs:
           mkdir -p packages/cdktn/dist/go
           ln -sfn "$PWD/dist/go/cdktn" packages/cdktn/dist/go/cdktn
       - name: examples integration tests
-        run: test/run-against-dist.mjs node tools/build-example.js ${TEST_TARGET}
+        run: test/run-against-dist.mjs node tools/build-example.mjs ${TEST_TARGET}
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
           TEST_TARGET: "${{ matrix.target }}"

.github/workflows/pnpm-upgrade.yml

@@ -11,7 +11,6 @@ on:
 # We special-case @types/fs-extra because the current major (9.x) is broken with @types/node >= 10
 # We special-case typescript because it's not semantically versioned
 # We special-case constructs because we want to stay in control of the minimum compatible version
-# We special-case lerna because we have a patch on it that stops applying if Lerna upgrades. Remove this once https://github.com/lerna/lerna/pull/2874 releases.
 # We special-case graphology-types because the newer version has type definitions that are not compatible with our typescript version.
 # We special-case @types/prettier because the underlying TS types aren't supported by our TS version anymore since prettier v2.6.1
 
@@ -41,20 +40,23 @@ jobs:
         uses: ./.github/actions/setup-corepack-pnpm
       - name: Install Tools
         run: |-
-          npm -g install lerna npm-check-updates@^9.0.0
+          npm -g install npm-check-updates@^9.0.0
+      # Install first so `nx` is available for the package listing below.
+      - name: Run "pnpm install"
+        run: pnpm install --prefer-offline
       - name: List Mono-Repo Packages
         id: list-packages
         # These need to be ignored from the `ncu` runs!
         run: |-
-          echo "list=$(node -p "$(lerna ls --all --json 2>/dev/null).map(item => item.name).join(',')")" >> $GITHUB_OUTPUT
+          echo "list=$(pnpm exec nx show projects --json | jq -r 'join(",")')" >> $GITHUB_OUTPUT
       - name: Run "ncu -u"
         run: |-
           # Upgrade dependencies at repository root
           ncu --upgrade --filter=@types/fs-extra --target=minor
           ncu --upgrade --filter=typescript --target=patch
-          ncu --upgrade --reject=@types/node,@types/fs-extra,constructs,typescript,lerna,@types/prettier --target=minor
+          ncu --upgrade --reject=@types/node,@types/fs-extra,constructs,typescript,@types/prettier --target=minor
 
-      # This will ensure the current lockfile is up-to-date with the dependency specifications (necessary for "pnpm update" to run)
+      # Refresh the lockfile after the ncu edits above (necessary for "pnpm update" to run)
       - name: Run "pnpm install"
         run: pnpm install --prefer-offline
 
@@ -163,19 +165,22 @@ jobs:
         uses: ./.github/actions/setup-corepack-pnpm
       - name: Install Tools
         run: |-
-          npm -g install lerna npm-check-updates@^9.0.0
+          npm -g install npm-check-updates@^9.0.0
+      # Install first so `nx` is available for the package listing below.
+      - name: Run "pnpm install"
+        run: pnpm install --prefer-offline
       - name: List Mono-Repo Packages
         id: list-packages
         # These need to be ignored from the `ncu` runs!
         run: |-
-          echo "list=$(node -p "$(lerna ls --all --json 2>/dev/null).map(item => item.name).join(',')")" >> $GITHUB_OUTPUT
+          echo "list=$(pnpm exec nx show projects --json | jq -r 'join(",")')" >> $GITHUB_OUTPUT
       - name: Run "ncu -u"
         run: |-
           # Upgrade all the packages
-          lerna exec --scope='{${{ join(matrix.pr.packages, ',') }}}' ncu -- --upgrade --filter=@types/fs-extra --target=minor
-          lerna exec --scope='{${{ join(matrix.pr.packages, ',') }}}' ncu -- --upgrade --filter=typescript --target=patch
-          lerna exec --scope='{${{ join(matrix.pr.packages, ',') }}}' ncu -- --upgrade --reject='@types/node,@types/fs-extra,constructs,typescript,graphology-types,jsii,jsii-pacmak,jsii-rosetta,jsii-docgen,codemaker,${{ steps.list-packages.outputs.list }}'  --target=minor
-      # This will ensure the current lockfile is up-to-date with the dependency specifications (necessary for "pnpm update" to run)
+          pnpm exec nx exec -p '${{ join(matrix.pr.packages, ',') }}' -- ncu --upgrade --filter=@types/fs-extra --target=minor
+          pnpm exec nx exec -p '${{ join(matrix.pr.packages, ',') }}' -- ncu --upgrade --filter=typescript --target=patch
+          pnpm exec nx exec -p '${{ join(matrix.pr.packages, ',') }}' -- ncu --upgrade --reject='@types/node,@types/fs-extra,constructs,typescript,graphology-types,jsii,jsii-pacmak,jsii-rosetta,jsii-docgen,codemaker,${{ steps.list-packages.outputs.list }}'  --target=minor
+      # Refresh the lockfile after the ncu edits above (necessary for "pnpm update" to run)
       - name: Run "pnpm install"
         run: pnpm install --prefer-offline
 
@@ -227,17 +232,20 @@ jobs:
         uses: ./.github/actions/setup-corepack-pnpm
       - name: Install Tools
         run: |-
-          npm -g install lerna npm-check-updates@^9.0.0
+          npm -g install npm-check-updates@^9.0.0
+      # Install first so `nx` is available for the package listing below.
+      - name: Run "pnpm install"
+        run: pnpm install --prefer-offline
       - name: List Mono-Repo Packages
         id: list-packages
         # These need to be ignored from the `ncu` runs!
         run: |-
-          echo "list=$(node -p "$(lerna ls --all --json 2>/dev/null).map(item => item.name).join(',')")" >> $GITHUB_OUTPUT
+          echo "list=$(pnpm exec nx show projects --json | jq -r 'join(",")')" >> $GITHUB_OUTPUT
       - name: Run "ncu -u"
         run: |-
           # Upgrade all the packages
-          lerna exec ncu -- --upgrade --filter='jsii,jsii-pacmak,jsii-rosetta,jsii-docgen,codemaker,constructs' --target=minor
-      # This will ensure the current lockfile is up-to-date with the dependency specifications (necessary for "pnpm update" to run)
+          pnpm exec nx exec -- ncu --upgrade --filter='jsii,jsii-pacmak,jsii-rosetta,jsii-docgen,codemaker,constructs' --target=minor
+      # Refresh the lockfile after the ncu edits above (necessary for "pnpm update" to run)
       - name: Run "pnpm install"
         run: pnpm install --prefer-offline
 

.github/workflows/pr-unit.yml

@@ -67,7 +67,7 @@ jobs:
         # @cdktn/hcl2cdk's globalSetup.ts spawns `cdktn init --dist=...` which
         # reads jsii tarballs from the workspace-root dist/ directory; that
         # output isn't produced by an Nx target chain, only by `pnpm run package`
-        # + tools/collect-dist.sh. Run it conditionally so unrelated PRs
+        # + tools/collect-dist.mjs. Run it conditionally so unrelated PRs
         # don't pay the multi-language packaging cost.
         run: |
           if pnpm exec nx show projects --affected --base="$NX_BASE" --head="$NX_HEAD" | grep -qx '@cdktn/hcl2cdk'; then

.github/workflows/release.yml

@@ -68,7 +68,7 @@ jobs:
         if: steps.get_release_status.outputs.release == 'unreleased'
         run: |
           pnpm ci
-          tools/align-version.sh
+          node tools/align-version.mjs
           pnpm run build
           pnpm run package
         env:
@@ -134,7 +134,7 @@ jobs:
       - name: Bump prerelease version
         run: |
           pnpm prepare-next-release
-          tools/align-version.sh
+          node tools/align-version.mjs
       - name: version
         id: get_version
         run: |

.github/workflows/unit.yml

@@ -64,7 +64,7 @@ jobs:
         run: |
           pnpm ci
       - name: align versions
-        run: tools/align-version.sh
+        run: node tools/align-version.mjs
       - name: package (when testing @cdktn/hcl2cdk)
         # hcl2cdk's globalSetup.ts spawns `cdktn init --dist=...` which reads
         # jsii tarballs from the workspace-root dist/ directory.

.gitignore

@@ -7,8 +7,6 @@
 !test.js
 *.d.ts
 node_modules
-!tools/build-example.js
-!tools/lint-examples.js
 
 # CDK asset staging directory
 .cdk.staging

.prettierignore

@@ -23,9 +23,6 @@ dist
 packages/@cdktn/provider-generator/edge-provider-bindings
 test/edge-provider-bindings
 !tools/documentation-generation/generate-documentation.js
-!tools/build-example.js
-!tools/lint-examples.js
-!tools/update-github-project-board/index.ts
 **/go.mod
 **/go.sum
 **/pnpm-lock.yaml

CONTRIBUTING.md

@@ -324,7 +324,7 @@ If you get this error message when trying to use a local build of `cdktn`:
 Run:
 
 ```
-./tools/align-version.sh -dev.111212112 && pnpm build && pnpm package
+node tools/align-version.mjs -dev.111212112 && pnpm build && pnpm package
 ```
 
 This builds a package with a development version which skips the tamper check in Python. (We once accidentally released `cdktn 0.0.0` which is the reason why Python knows some valid hashes for that `0.0.0` version and will fail as they won't match.)

docs/release-please.md

@@ -15,7 +15,7 @@ untouched and keys off `package.json` as it always has.
 
 This is a **locked-version JSII monorepo**: every package ships at the single
 root version. In git the sub-package `package.json`s stay at `0.0.0` and are
-aligned at build time by `tools/align-version.sh` (`lerna version`). Therefore
+aligned at build time by `tools/align-version.mjs` (`nx release version`). Therefore
 release-please manages a **single root release** (the `"."` package in
 `release-please-config.json`) — not independent per-package versions.
 

knip.jsonc

@@ -6,6 +6,9 @@
   "treatConfigHintsAsErrors": true,
   "workspaces": {
     ".": {
+      // The loose scripts under tools/ are invoked from package.json/CI, not imported;
+      // list them as entries so knip traces their dependencies
+      "entry": ["tools/*.mjs"],
       "ignoreDependencies": [
         // Required by the tools/extract-changelog script (run from tools/release-github.sh).
         "changelog-parser",