refactor: extract zip utilities into shared `@aws-cdk/tools` package by mrgrain · Pull Request #1512 · aws/aws-cdk-cli

mrgrain · 2026-05-14T14:38:57Z

Both cdk-assets-lib and toolkit-lib carried their own copy of the zip utilities (zipDirectory, zipString) wrapping archiver and fast-glob. This duplication made it easy for the implementations to drift apart — the toolkit-lib version had already lost the deterministic date reset, for example.

This PR introduces a new private (unpublished) @aws-cdk/tools package that hosts small, self-contained utilities. Each tool lives in its own subdirectory under lib/, is type-checked by tsc, and bundled by esbuild with --packages=external — so the bundled output contains only the code we wrote, while third-party packages stay as plain require(...) calls.

Consumer packages cherry-pick tools at pre-compile time via a useTools option on the new CdkTypeScriptWorkspace projen construct, using typed tool references (e.g. useTools: [tools.zip]). For each tool it:

copies the bundled .js/.d.ts into lib/private/tools/<name>/. These files are committed, so tsc --build of dependent projects (e.g. the CLI) can resolve them without first running this package's pre-compile step.
adds the tool's declared runtime dependencies (e.g. archiver, fast-glob) to the consuming package.

Keeping those dependencies external to the bundle (rather than inlining them) is deliberate. The aws-cdk CLI bundles cdk-assets-lib and toolkit-lib together; if each shipped its own inlined copy of archiver (and its lodash/fast-glob deps), the CLI bundle would carry the implementation multiple times. Declaring the deps and keeping them external lets the bundler resolve them to a single shared copy, matching the pre-refactor footprint.

Adding a new tool is just: create lib/<tool>/index.ts in the tools package, declare its third-party deps in toolDeps, and useTools: [tools.<tool>] in each consumer.

Checklist

This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
- Release notes for the new version:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

github-actions · 2026-05-14T14:39:26Z

Dependency Review

The following issues were found:

✅ 0 vulnerable package(s)
✅ 0 package(s) with incompatible licenses
✅ 0 package(s) with invalid SPDX license definitions
⚠️ 5 package(s) with unknown licenses.

See the Details below.

License Issues

packages/@aws-cdk/private-tools/package.json

Package	Version	License	Issue Type
archiver	^7.0.1	Null	Unknown License
fast-glob	^3.3.3	Null	Unknown License

packages/aws-cdk/package.json

Package	Version	License	Issue Type
@aws-cdk/private-tools	^0.0.0	Null	Unknown License

yarn.lock

Package	Version	License	Issue Type
@aws-cdk/private-tools@workspace:packages/	0.0.0-use.local	Null	Unknown License
cdklabs-projen-project-types	0.5.2	Null	Unknown License

OpenSSF Scorecard

Scorecard details

Package

Version

Score

Details

npm/cdklabs-projen-project-types

^0.5.2

Unknown

npm/@aws-cdk/private-tools

^0.0.0

Unknown

npm/esbuild

^0.28.0

Unknown

npm/@cdklabs/eslint-plugin

^2.0.8

Unknown

npm/@stylistic/eslint-plugin

^3

Unknown

npm/@types/archiver

^7.0.0

Unknown

npm/@types/jest

^29.5.14

Unknown

npm/@types/node

^20

Unknown

npm/@typescript-eslint/eslint-plugin

^8

Unknown

npm/@typescript-eslint/parser

^8

Unknown

npm/archiver

^7.0.1

Unknown

npm/constructs

^10.0.0

Unknown

npm/eslint

^9

Unknown

npm/eslint-config-prettier

^10.1.8

Unknown

npm/eslint-import-resolver-typescript

^4.4.5

Unknown

npm/eslint-plugin-import

^2.32.0

Unknown

npm/eslint-plugin-jest

^29.15.2

Unknown

npm/eslint-plugin-jsdoc

^62.9.0

Unknown

npm/eslint-plugin-prettier

^4.2.5

Unknown

npm/fast-glob

^3.3.3

Unknown

npm/jest

^29.7.0

Unknown

npm/jest-junit

^16

Unknown

npm/jszip

^3.10.1

Unknown

npm/nx

^22.7.5

Unknown

npm/prettier

^2.8

Unknown

npm/projen

^0.99.70

Unknown

npm/ts-jest

^29.4.9

Unknown

npm/typescript

5.9

Unknown

npm/@aws-cdk/private-tools

^0.0.0

Unknown

npm/esbuild

^0.28.0

Unknown

npm/@aws-cdk/private-tools

^0.0.0

Unknown

npm/@aws-cdk/private-tools@workspace:packages/

0.0.0-use.local

Unknown

npm/@types/archiver

7.0.0

🟢 6.5

Details

Check	Score	Reason
Maintained	🟢 10	30 commit(s) and 3 issue activity found in the last 90 days -- score normalized to 10
Code-Review	🟢 8	Found 25/29 approved changesets -- score normalized to 8
Packaging	⚠️ -1	packaging workflow not detected
CII-Best-Practices	⚠️ 0	no effort to earn an OpenSSF best practices badge detected
Dangerous-Workflow	🟢 10	no dangerous workflow patterns detected
Token-Permissions	⚠️ 0	detected GitHub workflow tokens with excessive permissions
Security-Policy	🟢 10	security policy file detected
License	🟢 9	license file detected
Signed-Releases	⚠️ -1	no releases found
Branch-Protection	⚠️ -1	internal error: error during branchesHandler.setup: internal error: some github tokens can't read classic branch protection rules: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md
SAST	⚠️ 0	SAST tool is not run on all commits -- score normalized to 0
Pinned-Dependencies	🟢 8	dependency not pinned by hash detected -- score normalized to 8
Binary-Artifacts	🟢 10	no binaries found in the repo
Fuzzing	⚠️ 0	project is not fuzzed

npm/cdklabs-projen-project-types

0.5.2

Unknown

npm/ts-jest

29.4.9

🟢 5.4

Details

Check	Score	Reason
Maintained	🟢 10	30 commit(s) and 3 issue activity found in the last 90 days -- score normalized to 10
Code-Review	🟢 10	all changesets reviewed
Dangerous-Workflow	⚠️ 0	dangerous workflow patterns detected
Packaging	⚠️ -1	packaging workflow not detected
CII-Best-Practices	⚠️ 0	no effort to earn an OpenSSF best practices badge detected
Token-Permissions	⚠️ 0	detected GitHub workflow tokens with excessive permissions
Binary-Artifacts	🟢 10	no binaries found in the repo
Pinned-Dependencies	🟢 10	all dependencies are pinned
Security-Policy	⚠️ 0	security policy file not detected
Fuzzing	⚠️ 0	project is not fuzzed
License	🟢 10	license file detected
Signed-Releases	⚠️ -1	no releases found
Branch-Protection	⚠️ -1	internal error: error during branchesHandler.setup: internal error: some github tokens can't read classic branch protection rules: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md
SAST	🟢 10	SAST tool is run on all commits

Scanned Files

package.json
packages/@aws-cdk/cdk-assets-lib/package.json
packages/@aws-cdk/private-tools/package.json
packages/@aws-cdk/toolkit-lib/package.json
packages/aws-cdk/package.json
yarn.lock

codecov-commenter · 2026-06-05T10:20:48Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.64%. Comparing base (3ec7934) to head (6fb9c8e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1512   +/-   ##
=======================================
  Coverage   88.64%   88.64%           
=======================================
  Files          77       77           
  Lines       11293    11293           
  Branches     1565     1565           
=======================================
  Hits        10011    10011           
  Misses       1253     1253           
  Partials       29       29

Flag	Coverage Δ
suite.unit	`88.64% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-06-10T13:54:50Z

Total lines changed 2254 is greater than 1000. Please consider breaking this PR down.

codecov-commenter · 2026-06-10T16:09:57Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.73%. Comparing base (1705f43) to head (73d8f7e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1512   +/-   ##
=======================================
  Coverage   88.73%   88.73%           
=======================================
  Files          77       77           
  Lines       11359    11359           
  Branches     1585     1584    -1     
=======================================
  Hits        10079    10079           
  Misses       1250     1250           
  Partials       30       30

Flag	Coverage Δ
suite.unit	`88.73% <100.00%> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…ols` Replace the custom `CdkTypeScriptWorkspace` subclass with a `ToolMixin` that implements projen's `IMixin` interface. Consumers now use: const project = new yarn.TypeScriptWorkspace({ ... }); project.with(tools.zip); Also renames `@aws-cdk/tools` to `@aws-cdk/private-tools` to make it clear this is not a published package. The `defineTools` function now accepts a formal `tools: Record<string, ToolDefinition>` where each tool declares its `deps` and optional `devDeps`.

mrgrain had a problem deploying to automation May 14, 2026 14:39 — with GitHub Actions Failure

mrgrain temporarily deployed to automation May 14, 2026 14:39 — with GitHub Actions Inactive

mrgrain had a problem deploying to no-approval May 14, 2026 14:39 — with GitHub Actions Failure

github-actions Bot added the p2 label May 14, 2026

aws-cdk-automation requested a review from a team May 14, 2026 14:39

mrgrain force-pushed the mrgrain/refactor/tools/extract-zip-into-shared-tools-package branch from 619a9b9 to 6a6d511 Compare June 5, 2026 09:51

mrgrain had a problem deploying to no-approval June 5, 2026 09:51 — with GitHub Actions Failure

aws-cdk-automation temporarily deployed to no-approval June 5, 2026 09:59 — with GitHub Actions Inactive

aws-cdk-automation had a problem deploying to run-tests June 5, 2026 10:03 — with GitHub Actions Failure

mrgrain had a problem deploying to run-tests June 5, 2026 10:14 — with GitHub Actions Failure

mrgrain force-pushed the mrgrain/refactor/tools/extract-zip-into-shared-tools-package branch from 9fca289 to cecbc10 Compare June 5, 2026 10:42

mrgrain temporarily deployed to no-approval June 5, 2026 10:42 — with GitHub Actions Inactive

rix0rrr reviewed Jun 11, 2026

View reviewed changes

Comment thread .projenrc.ts Outdated

rix0rrr approved these changes Jun 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: extract zip utilities into shared `@aws-cdk/tools` package#1512

refactor: extract zip utilities into shared `@aws-cdk/tools` package#1512
mrgrain merged 1 commit into
mainfrom
mrgrain/refactor/tools/extract-zip-into-shared-tools-package

mrgrain commented May 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 14, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Jun 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

codecov-commenter commented Jun 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

mrgrain commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

License Issues

packages/@aws-cdk/private-tools/package.json

packages/aws-cdk/package.json

yarn.lock

OpenSSF Scorecard

Scanned Files

Uh oh!

codecov-commenter commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

codecov-commenter commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mrgrain commented May 14, 2026 •

edited

Loading

github-actions Bot commented May 14, 2026 •

edited

Loading

codecov-commenter commented Jun 5, 2026 •

edited

Loading

codecov-commenter commented Jun 10, 2026 •

edited

Loading