feat(lib): Initial Asset Pipeline implementation

[eduardomourar]

Related issue

Fully Resolves:

• Fixes Helper for using local files hashicorp/terraform-cdk#708 - Helper for using local files
• Fixes TerraformAsset: add bundling feature hashicorp/terraform-cdk#3919 - TerraformAsset: add bundling feature
• Fixes Allow to ignore files from TerraformAsset hashicorp/terraform-cdk#2113 - Allow to ignore files from TerraformAsset

Partially Addresses:

• Assets: Add documentation around TerraformCachedAsset hashicorp/terraform-cdk#2711 - Assets: Add documentation (implementation done, docs needed)

Description

Implements a simplified asset staging and bundling pipeline for CDKTN, following patterns from AWS CDK and TerraConstructs while avoiding unnecessary dependencies.

✅ Implemented Features

Core Asset Staging

• AssetStaging construct for staging files and directories
• Hash calculation with multiple strategies:
  • SOURCE - based on source content (default)
  • OUTPUT - based on bundled output
  • CUSTOM - user-provided hash
• Archive detection for .zip, .tar, .tar.gz, .tgz files
• Asset caching - reuse staged assets with identical content
• Exclusion patterns - filter files during staging
• Extra hash - cache busting mechanism

Docker Bundling

• Local bundling with Docker fallback via ILocalBundling interface
• Docker command construction with support for:
  • Custom images, commands, and entrypoints
  • Environment variables, user, network, platform
  • Security options and working directory
• Bundling output types:
  • ARCHIVED - single archive file
  • NOT_ARCHIVED - directory of files
  • SINGLE_FILE - single non-archive file
  • AUTO_DISCOVER - automatic detection

Test Coverage

• 87 asset-related tests (+50% coverage increase)
• Comprehensive patterns from AWS CDK tests
• Unit tests for Docker command construction
• Integration tests for end-to-end workflows
• Edge cases: empty dirs, special chars, symlinks, binary files

⏸️ Intentionally Deferred

To maintain simplicity and avoid new dependencies.

Not Implemented from AWS CDK/TerraConstructs:

• esbuild bundling - would require esbuild dependency
• Advanced Docker features - volume copy variant, advanced mount modes
• Asset synthesis integration - cloud assembly manifest, stack metadata
• Asset publishing - S3 upload, publishing manifest
• Advanced caching - disk-based cache, complex invalidation

Rationale: These features add significant complexity and external dependencies that aren't needed for the initial use case. The current implementation provides all core functionality (staging, hashing, bundling) with extensible interfaces for future enhancements.

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