cdktn 0.25.0.dev38__tar.gz → 0.25.0.dev40__tar.gz

{cdktn-0.25.0.dev38/src/cdktn.egg-info → cdktn-0.25.0.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cdktn
-Version: 0.25.0.dev38
+Version: 0.25.0.dev40
 Summary: Cloud Development Kit for Terraform
 Home-page: https://github.com/open-constructs/cdk-terrain
 Author: OpenConstructs

{cdktn-0.25.0.dev38 → cdktn-0.25.0.dev40}/setup.py

@@ -5,7 +5,7 @@ kwargs = json.loads(
     """
 {
     "name": "cdktn",
-    "version": "0.25.0.dev38",
+    "version": "0.25.0.dev40",
     "description": "Cloud Development Kit for Terraform",
     "license": "MPL-2.0",
     "url": "https://github.com/open-constructs/cdk-terrain",
@@ -27,7 +27,7 @@ kwargs = json.loads(
     ],
     "package_data": {
         "cdktn._jsii": [
-            "cdktn@0.25.0-pre.38.jsii.tgz"
+            "cdktn@0.25.0-pre.40.jsii.tgz"
         ],
         "cdktn": [
             "py.typed"

{cdktn-0.25.0.dev38 → cdktn-0.25.0.dev40}/src/cdktn/__init__.py

@@ -635,9 +635,8 @@ class AssetHashOptions:
 class AssetHashType(enum.Enum):
     '''(experimental) The type of asset hash.
 
-    NOTE: the hash is used in order to identify a specific revision of the asset, and
-    used for optimizing and caching deployment activities related to this asset such as
-    packaging, uploading to cloud storage, etc.
+    The hash identifies a specific revision of the asset and caches deployment
+    work such as packaging and uploading.
 
     :stability: experimental
     '''
@@ -645,16 +644,15 @@ class AssetHashType(enum.Enum):
     SOURCE = "SOURCE"
     '''(experimental) Based on the content of the source path.
 
-    Use ``SOURCE`` when the content of the asset changes frequently or when
-    you want to track changes to the source files directly.
+    Use ``SOURCE`` to track changes to the source files directly.
 
     :stability: experimental
     '''
     OUTPUT = "OUTPUT"
     '''(experimental) Based on the content of the bundling output.
 
-    Use ``OUTPUT`` when the source of the asset is a top level folder containing
-    code and/or dependencies that are not directly linked to the asset.
+    Use ``OUTPUT`` when the source is a top-level folder holding code and/or
+    dependencies not directly linked to the asset.
 
     :stability: experimental
     '''
@@ -677,9 +675,9 @@ class AssetOptions:
         asset_hash: typing.Optional[builtins.str] = None,
         asset_hash_type: typing.Optional["AssetHashType"] = None,
     ) -> None:
-        '''(experimental) Asset hash options.
+        '''(experimental) Options controlling how an asset's hash is derived.
 
-        :param asset_hash: (experimental) Specify a custom hash for this asset. If ``assetHashType`` is set it must be set to ``AssetHashType.CUSTOM``. The value is used verbatim as the asset hash, and because it names the staged asset file it may only contain letters, digits, ``_``, ``.`` and ``-``. NOTE: the hash is used in order to identify a specific revision of the asset, and used for optimizing and caching deployment activities related to this asset such as packaging, uploading to cloud storage, etc. If you chose to customize the hash, you will need to make sure it is updated every time the asset changes, or otherwise it is possible that some deployments will not be invalidated. Default: - based on ``assetHashType``
+        :param asset_hash: (experimental) Specify a custom hash for this asset. If ``assetHashType`` is set it must be set to ``AssetHashType.CUSTOM``. The value is used verbatim as the asset hash, and because it names the staged asset file it may only contain letters, digits, ``_``, ``.`` and ``-``. The hash identifies a specific revision of the asset and caches deployment work (packaging, uploading). A custom hash must be updated whenever the asset changes, or some deployments will not be invalidated. Default: - based on ``assetHashType``
         :param asset_hash_type: (experimental) Specifies the type of hash to calculate for this asset. If ``assetHash`` is configured, this option must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: - the default is ``AssetHashType.SOURCE``, but if ``assetHash`` is explicitly specified this value defaults to ``AssetHashType.CUSTOM``.
 
         :stability: experimental
@@ -703,11 +701,9 @@ class AssetOptions:
         hash, and because it names the staged asset file it may only contain
         letters, digits, ``_``, ``.`` and ``-``.
 
-        NOTE: the hash is used in order to identify a specific revision of the asset, and
-        used for optimizing and caching deployment activities related to this asset such as
-        packaging, uploading to cloud storage, etc. If you chose to customize the hash, you will
-        need to make sure it is updated every time the asset changes, or otherwise it is
-        possible that some deployments will not be invalidated.
+        The hash identifies a specific revision of the asset and caches deployment
+        work (packaging, uploading). A custom hash must be updated whenever the
+        asset changes, or some deployments will not be invalidated.
 
         :default: - based on ``assetHashType``
 
@@ -790,6 +786,8 @@ class AssetPackaging(metaclass=jsii.JSIIMeta, jsii_type="cdktn.AssetPackaging"):
         "asset_hash_type": "assetHashType",
         "packaging": "packaging",
         "source_path": "sourcePath",
+        "bundler": "bundler",
+        "display_name": "displayName",
         "exclude": "exclude",
         "extra_hash": "extraHash",
         "ignore_strategy": "ignoreStrategy",
@@ -803,16 +801,20 @@ class AssetStagingOptions(AssetOptions):
         asset_hash_type: typing.Optional["AssetHashType"] = None,
         packaging: "IAssetPackaging",
         source_path: builtins.str,
+        bundler: typing.Optional["IAssetBundler"] = None,
+        display_name: typing.Optional[builtins.str] = None,
         exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
         extra_hash: typing.Optional[builtins.str] = None,
         ignore_strategy: typing.Optional["IIgnoreStrategy"] = None,
     ) -> None:
         '''(experimental) Options for {@link AssetStaging}.
 
-        :param asset_hash: (experimental) Specify a custom hash for this asset. If ``assetHashType`` is set it must be set to ``AssetHashType.CUSTOM``. The value is used verbatim as the asset hash, and because it names the staged asset file it may only contain letters, digits, ``_``, ``.`` and ``-``. NOTE: the hash is used in order to identify a specific revision of the asset, and used for optimizing and caching deployment activities related to this asset such as packaging, uploading to cloud storage, etc. If you chose to customize the hash, you will need to make sure it is updated every time the asset changes, or otherwise it is possible that some deployments will not be invalidated. Default: - based on ``assetHashType``
+        :param asset_hash: (experimental) Specify a custom hash for this asset. If ``assetHashType`` is set it must be set to ``AssetHashType.CUSTOM``. The value is used verbatim as the asset hash, and because it names the staged asset file it may only contain letters, digits, ``_``, ``.`` and ``-``. The hash identifies a specific revision of the asset and caches deployment work (packaging, uploading). A custom hash must be updated whenever the asset changes, or some deployments will not be invalidated. Default: - based on ``assetHashType``
         :param asset_hash_type: (experimental) Specifies the type of hash to calculate for this asset. If ``assetHash`` is configured, this option must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: - the default is ``AssetHashType.SOURCE``, but if ``assetHash`` is explicitly specified this value defaults to ``AssetHashType.CUSTOM``.
         :param packaging: (experimental) How the staged result is produced and shaped. The caller decides this (e.g. from its own ``AssetType``) — ``AssetStaging`` never infers or changes it based on ``exclude``/``extraHash``.
         :param source_path: (experimental) Absolute path to the source file or directory. Resolving a relative path against ``cdktf.json`` is the caller's responsibility.
+        :param bundler: (experimental) A bundler that builds the source into an artifact before staging. Under the default ``SOURCE`` hashing the build is deferred to ``stage()`` and stays skippable; ``OUTPUT`` hashing builds eagerly at construction time to hash the artifact, forgoing skippability. The bundler's declared output shape must match the packaging: a ``BundleResult.directory`` needs a directory-accepting packaging, a ``BundleResult.file`` a single-file one (``AssetType.FILE``). The mismatch is caught once the build runs. Default: - the source is staged verbatim, with no build step
+        :param display_name: (experimental) Identifier used in error messages, so they name the user-facing construct (e.g. the ``TerraformAsset``) rather than this internal staging child. Default: - the staging construct's own id
         :param exclude: (experimental) Paths to exclude, relative to ``sourcePath``. Cannot be combined with ``ignoreStrategy``, which replaces this matcher rather than layering on top of it. Default: - nothing is excluded
         :param extra_hash: (experimental) Extra information to fold into the hash (e.g. build instructions and other inputs). Default: - no extra hash
         :param ignore_strategy: (experimental) Exclusion matching, for callers that need ``.gitignore`` / ``.dockerignore`` parity rather than the built-in exact-path / suffix / directory matcher. Default: - ``exclude`` is used with the built-in matcher
@@ -825,6 +827,8 @@ class AssetStagingOptions(AssetOptions):
             check_type(argname="argument asset_hash_type", value=asset_hash_type, expected_type=type_hints["asset_hash_type"])
             check_type(argname="argument packaging", value=packaging, expected_type=type_hints["packaging"])
             check_type(argname="argument source_path", value=source_path, expected_type=type_hints["source_path"])
+            check_type(argname="argument bundler", value=bundler, expected_type=type_hints["bundler"])
+            check_type(argname="argument display_name", value=display_name, expected_type=type_hints["display_name"])
             check_type(argname="argument exclude", value=exclude, expected_type=type_hints["exclude"])
             check_type(argname="argument extra_hash", value=extra_hash, expected_type=type_hints["extra_hash"])
             check_type(argname="argument ignore_strategy", value=ignore_strategy, expected_type=type_hints["ignore_strategy"])
@@ -836,6 +840,10 @@ class AssetStagingOptions(AssetOptions):
             self._values["asset_hash"] = asset_hash
         if asset_hash_type is not None:
             self._values["asset_hash_type"] = asset_hash_type
+        if bundler is not None:
+            self._values["bundler"] = bundler
+        if display_name is not None:
+            self._values["display_name"] = display_name
         if exclude is not None:
             self._values["exclude"] = exclude
         if extra_hash is not None:
@@ -852,11 +860,9 @@ class AssetStagingOptions(AssetOptions):
         hash, and because it names the staged asset file it may only contain
         letters, digits, ``_``, ``.`` and ``-``.
 
-        NOTE: the hash is used in order to identify a specific revision of the asset, and
-        used for optimizing and caching deployment activities related to this asset such as
-        packaging, uploading to cloud storage, etc. If you chose to customize the hash, you will
-        need to make sure it is updated every time the asset changes, or otherwise it is
-        possible that some deployments will not be invalidated.
+        The hash identifies a specific revision of the asset and caches deployment
+        work (packaging, uploading). A custom hash must be updated whenever the
+        asset changes, or some deployments will not be invalidated.
 
         :default: - based on ``assetHashType``
 
@@ -909,6 +915,35 @@ class AssetStagingOptions(AssetOptions):
         assert result is not None, "Required property 'source_path' is missing"
         return typing.cast(builtins.str, result)
 
+    @builtins.property
+    def bundler(self) -> typing.Optional["IAssetBundler"]:
+        '''(experimental) A bundler that builds the source into an artifact before staging.
+
+        Under the default ``SOURCE`` hashing the build is deferred to ``stage()`` and
+        stays skippable; ``OUTPUT`` hashing builds eagerly at construction time to
+        hash the artifact, forgoing skippability. The bundler's declared output
+        shape must match the packaging: a ``BundleResult.directory`` needs a
+        directory-accepting packaging, a ``BundleResult.file`` a single-file one
+        (``AssetType.FILE``). The mismatch is caught once the build runs.
+
+        :default: - the source is staged verbatim, with no build step
+
+        :stability: experimental
+        '''
+        result = self._values.get("bundler")
+        return typing.cast(typing.Optional["IAssetBundler"], result)
+
+    @builtins.property
+    def display_name(self) -> typing.Optional[builtins.str]:
+        '''(experimental) Identifier used in error messages, so they name the user-facing construct (e.g. the ``TerraformAsset``) rather than this internal staging child.
+
+        :default: - the staging construct's own id
+
+        :stability: experimental
+        '''
+        result = self._values.get("display_name")
+        return typing.cast(typing.Optional[builtins.str], result)
+
     @builtins.property
     def exclude(self) -> typing.Optional[typing.List[builtins.str]]:
         '''(experimental) Paths to exclude, relative to ``sourcePath``.
@@ -1455,6 +1490,246 @@ class AzurermBackendConfig:
         )
 
 
+@jsii.data_type(
+    jsii_type="cdktn.BundleOptions",
+    jsii_struct_bases=[],
+    name_mapping={"output_dir": "outputDir", "source": "source"},
+)
+class BundleOptions:
+    def __init__(self, *, output_dir: builtins.str, source: builtins.str) -> None:
+        '''(experimental) Options handed to an {@link IAssetBundler} when it runs.
+
+        A struct rather than positional parameters: adding a field is additive,
+        adding a method parameter is not, and ``bundle`` is called through JSII where
+        that distinction is a breaking-change boundary.
+
+        :param output_dir: (experimental) A scratch directory the bundler may write into, owned and created by the caller. The bundler produces its output here (or in a subdirectory) and returns a {@link BundleResult} pointing at the finished artifact — see {@link IAssetBundler.bundle}.
+        :param source: (experimental) Absolute path to the asset's source file or directory. The bundler reads from here and must not modify it. Exclusions (``exclude`` / ``ignoreStrategy``) are already applied: when any are configured this points at a filtered copy, not the original tree, so the bundler reads exactly the file set the asset hash was taken over.
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__e4984c7b158b6fd9f304d19bf1be6b525991aa5c57db01aa1dd6d282c3369f9e)
+            check_type(argname="argument output_dir", value=output_dir, expected_type=type_hints["output_dir"])
+            check_type(argname="argument source", value=source, expected_type=type_hints["source"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {
+            "output_dir": output_dir,
+            "source": source,
+        }
+
+    @builtins.property
+    def output_dir(self) -> builtins.str:
+        '''(experimental) A scratch directory the bundler may write into, owned and created by the caller.
+
+        The bundler produces its output here (or in a subdirectory) and
+        returns a {@link BundleResult} pointing at the finished artifact — see
+        {@link IAssetBundler.bundle}.
+
+        :stability: experimental
+        '''
+        result = self._values.get("output_dir")
+        assert result is not None, "Required property 'output_dir' is missing"
+        return typing.cast(builtins.str, result)
+
+    @builtins.property
+    def source(self) -> builtins.str:
+        '''(experimental) Absolute path to the asset's source file or directory. The bundler reads from here and must not modify it.
+
+        Exclusions (``exclude`` / ``ignoreStrategy``) are already applied: when any
+        are configured this points at a filtered copy, not the original tree, so
+        the bundler reads exactly the file set the asset hash was taken over.
+
+        :stability: experimental
+        '''
+        result = self._values.get("source")
+        assert result is not None, "Required property 'source' is missing"
+        return typing.cast(builtins.str, result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "BundleOptions(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
+@jsii.enum(jsii_type="cdktn.BundleOutputType")
+class BundleOutputType(enum.Enum):
+    '''(experimental) The shape of a bundler's output, so staging and packaging can treat a single-file artifact (a tarball, a ``.zip``) differently from a directory tree without inferring it from the path.
+
+    :stability: experimental
+    '''
+
+    DIRECTORY = "DIRECTORY"
+    '''(experimental) The output is a directory tree.
+
+    Packaged like an unbundled source directory. The default, and the only
+    shape that predates archive support.
+
+    :stability: experimental
+    '''
+    FILE = "FILE"
+    '''(experimental) The output is a single file the bundler already produced in its final form.
+
+    A tarball or a deterministic ``.zip``. Staged verbatim rather than
+    re-archived, so ``AssetType.FILE`` no longer has to reject a bundler.
+
+    :stability: experimental
+    '''
+
+
+class BundleResult(metaclass=jsii.JSIIMeta, jsii_type="cdktn.BundleResult"):
+    '''(experimental) What a bundler produced, returned from {@link IAssetBundler.bundle}.
+
+    Carries the artifact path and its shape, or a declined state signalling the
+    caller should fall back. See {@link declined} for the decline protocol.
+
+    :stability: experimental
+    '''
+
+    @jsii.member(jsii_name="declined")
+    @builtins.classmethod
+    def declined(cls) -> "BundleResult":
+        '''(experimental) The bundler declined to run here; the caller should fall back.
+
+        Distinct from a thrown error, which is a hard failure.
+
+        :stability: experimental
+        '''
+        return typing.cast("BundleResult", jsii.sinvoke(cls, "declined", []))
+
+    @jsii.member(jsii_name="directory")
+    @builtins.classmethod
+    def directory(cls, path: builtins.str) -> "BundleResult":
+        '''(experimental) A directory-tree artifact at ``path``.
+
+        :param path: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__cb448e5d937b8e66717fe97ab740ea1924edd313428fa2e65c41a3f2d7c1a24c)
+            check_type(argname="argument path", value=path, expected_type=type_hints["path"])
+        return typing.cast("BundleResult", jsii.sinvoke(cls, "directory", [path]))
+
+    @jsii.member(jsii_name="file")
+    @builtins.classmethod
+    def file(cls, path: builtins.str) -> "BundleResult":
+        '''(experimental) A single-file artifact at ``path`` (a tarball, a ``.zip``), staged verbatim.
+
+        :param path: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__e6adf0d1d61dee6269a50f7bde47aef784df796b53286fb04ab6c071a75d6975)
+            check_type(argname="argument path", value=path, expected_type=type_hints["path"])
+        return typing.cast("BundleResult", jsii.sinvoke(cls, "file", [path]))
+
+    @builtins.property
+    @jsii.member(jsii_name="isDeclined")
+    def is_declined(self) -> builtins.bool:
+        '''(experimental) Whether the bundler declined to run, signalling the caller to fall back.
+
+        :stability: experimental
+        '''
+        return typing.cast(builtins.bool, jsii.get(self, "isDeclined"))
+
+    @builtins.property
+    @jsii.member(jsii_name="outputType")
+    def output_type(self) -> typing.Optional["BundleOutputType"]:
+        '''(experimental) The artifact's shape, or undefined when {@link isDeclined}.
+
+        :stability: experimental
+        '''
+        return typing.cast(typing.Optional["BundleOutputType"], jsii.get(self, "outputType"))
+
+    @builtins.property
+    @jsii.member(jsii_name="path")
+    def path(self) -> typing.Optional[builtins.str]:
+        '''(experimental) The artifact path, or undefined when {@link isDeclined}.
+
+        :stability: experimental
+        '''
+        return typing.cast(typing.Optional[builtins.str], jsii.get(self, "path"))
+
+
+class BundlerKey(metaclass=jsii.JSIIMeta, jsii_type="cdktn.BundlerKey"):
+    '''(experimental) Builds an {@link IAssetBundler.bundlerKey} from an ordered set of parts.
+
+    A ``bundlerKey`` has to serialize everything that can move a build's output;
+    done ad hoc, every bundler invents its own delimiter and forgets an input
+    differently. This gives the convention one implementation: parts are joined
+    with a separator that is escaped inside values, so distinct inputs cannot
+    collide into the same key.
+
+    :stability: experimental
+
+    Example::
+
+        const key = BundlerKey.of("docker", image, command)
+          .withEnv({ NODE_ENV: nodeEnv })
+          .toString();
+    '''
+
+    @jsii.member(jsii_name="of")
+    @builtins.classmethod
+    def of(cls, *parts: builtins.str) -> "BundlerKey":
+        '''(experimental) Start a key from an ordered list of parts.
+
+        Order is significant: it is part of what the key identifies.
+
+        :param parts: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__76b2ba8d3e61fcbea83025fd36866ed49e2970a52cbe09f43be16a01cf5a6858)
+            check_type(argname="argument parts", value=parts, expected_type=typing.Tuple[type_hints["parts"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast("BundlerKey", jsii.sinvoke(cls, "of", [*parts]))
+
+    @jsii.member(jsii_name="add")
+    def add(self, *parts: builtins.str) -> "BundlerKey":
+        '''(experimental) Append parts, returning a new key.
+
+        :param parts: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__5542e2e8a7f529585fff07dcaf5ca7a0425baa3a9af1286723c0b3fb21d976c6)
+            check_type(argname="argument parts", value=parts, expected_type=typing.Tuple[type_hints["parts"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast("BundlerKey", jsii.invoke(self, "add", [*parts]))
+
+    @jsii.member(jsii_name="toString")
+    def to_string(self) -> builtins.str:
+        '''(experimental) Render the collected parts to the string passed as ``bundlerKey``.
+
+        :stability: experimental
+        '''
+        return typing.cast(builtins.str, jsii.invoke(self, "toString", []))
+
+    @jsii.member(jsii_name="withEnv")
+    def with_env(
+        self,
+        entries: typing.Mapping[builtins.str, builtins.str],
+    ) -> "BundlerKey":
+        '''(experimental) Append ``key=value`` parts for a record, sorted by key so the result does not depend on property order.
+
+        :param entries: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__89d2ee0220c33c5357157d502001eb29e4d7acc5dd0985be2aeb7f269d3ef50b)
+            check_type(argname="argument entries", value=entries, expected_type=type_hints["entries"])
+        return typing.cast("BundlerKey", jsii.invoke(self, "withEnv", [entries]))
+
+
 @jsii.data_type(
     jsii_type="cdktn.CloudBackendConfig",
     jsii_struct_bases=[],
@@ -5335,11 +5610,10 @@ class IAsset(typing_extensions.Protocol):
     @builtins.property
     @jsii.member(jsii_name="assetHash")
     def asset_hash(self) -> builtins.str:
-        '''(experimental) A hash of this asset, which is available at construction time.
+        '''(experimental) A hash of this asset, available at construction time.
 
-        As this is a plain string, it
-        can be used in construct IDs in order to enforce creation of a new resource when the content
-        hash has changed.
+        Being a plain string, it can be used in construct IDs to force a new
+        resource when the content hash changes.
 
         :stability: experimental
         '''
@@ -5357,11 +5631,10 @@ class _IAssetProxy:
     @builtins.property
     @jsii.member(jsii_name="assetHash")
     def asset_hash(self) -> builtins.str:
-        '''(experimental) A hash of this asset, which is available at construction time.
+        '''(experimental) A hash of this asset, available at construction time.
 
-        As this is a plain string, it
-        can be used in construct IDs in order to enforce creation of a new resource when the content
-        hash has changed.
+        Being a plain string, it can be used in construct IDs to force a new
+        resource when the content hash changes.
 
         :stability: experimental
         '''
@@ -5371,6 +5644,192 @@ class _IAssetProxy:
 typing.cast(typing.Any, IAsset).__jsii_proxy_class__ = lambda : _IAssetProxy
 
 
+@jsii.interface(jsii_type="cdktn.IAssetBundler")
+class IAssetBundler(typing_extensions.Protocol):
+    '''(experimental) Transforms a source tree into a built artifact. Runs at synth, before the output is packaged and staged.
+
+    This is the extension point for asset bundling: core ships no bundler.
+    Docker, esbuild, pip, ``go build``, and similar are an open-ended, non
+    cloud-specific set, so each lives in its own package and implements this
+    one interface — the same way {@link IIgnoreStrategy} lets richer exclusion
+    live outside core. Users pass an instance via the consuming construct's
+    ``bundler`` option.
+
+    ``bundle`` runs during the owning construct's ``onSynthesize`` hook and may
+    touch the filesystem. Deferring it there keeps it skippable when the asset's
+    stack is not being synthesized, which holds as long as the hash is taken
+    over the source rather than the built output.
+
+    Bundlers compose through {@link ChainBundler} rather than a hierarchy: a
+    bundler declines (see {@link BundleResult.declined}) instead of failing when
+    it cannot run, and the chain falls through to the next.
+
+    :stability: experimental
+    '''
+
+    @builtins.property
+    @jsii.member(jsii_name="bundlerKey")
+    def bundler_key(self) -> typing.Optional[builtins.str]:
+        '''(experimental) A value identifying the build, folded into the asset hash.
+
+        The source tree alone cannot see the build, so swapping a ``node:18`` base
+        image for ``node:20`` would otherwise leave identity unchanged. Under
+        ``SOURCE`` hashing this is the only channel by which the build reaches
+        identity, so it must serialize every input that can move the output, or a
+        changed build silently reuses a stale artifact. {@link BundlerKey} builds
+        one from an ordered set of parts.
+
+        Mirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be
+        summarized as a string, and fall back to ``extraHash``.
+
+        :default: - the build does not contribute to the hash
+
+        :stability: experimental
+        '''
+        ...
+
+    @builtins.property
+    @jsii.member(jsii_name="outputFileName")
+    def output_file_name(self) -> typing.Optional[builtins.str]:
+        '''(experimental) The name a single-file artifact is staged under (e.g. ``archive.zip``).
+
+        A file-producing bundler (``BundleResult.file``) staged with
+        ``AssetType.FILE`` would otherwise take the source path's basename, which is
+        a directory name when the source is a directory. Declaring the name here
+        lets the artifact reflect what the bundler produces. It is static
+        configuration, needed at construction before a deferred ``SOURCE`` build
+        runs, not the file's runtime name.
+
+        Valid only for a file-producing bundler: setting it with a directory
+        packaging (anything but ``AssetType.FILE``) is rejected at construction.
+
+        :default: - the source path's basename
+
+        :stability: experimental
+        '''
+        ...
+
+    @jsii.member(jsii_name="bundle")
+    def bundle(
+        self,
+        *,
+        output_dir: builtins.str,
+        source: builtins.str,
+    ) -> "BundleResult":
+        '''(experimental) Produce the artifact and return a {@link BundleResult} describing it.
+
+        Implementations write into ``options.outputDir`` and never write back to
+        ``options.source``. The returned path must exist and match its declared
+        shape, or staging rejects it.
+
+        A bundler that cannot run in this environment returns
+        ``BundleResult.declined()`` so a {@link ChainBundler} can fall through to
+        the next; a thrown error is a hard failure, not a decline.
+
+        :param output_dir: (experimental) A scratch directory the bundler may write into, owned and created by the caller. The bundler produces its output here (or in a subdirectory) and returns a {@link BundleResult} pointing at the finished artifact — see {@link IAssetBundler.bundle}.
+        :param source: (experimental) Absolute path to the asset's source file or directory. The bundler reads from here and must not modify it. Exclusions (``exclude`` / ``ignoreStrategy``) are already applied: when any are configured this points at a filtered copy, not the original tree, so the bundler reads exactly the file set the asset hash was taken over.
+
+        :stability: experimental
+        '''
+        ...
+
+
+class _IAssetBundlerProxy:
+    '''(experimental) Transforms a source tree into a built artifact. Runs at synth, before the output is packaged and staged.
+
+    This is the extension point for asset bundling: core ships no bundler.
+    Docker, esbuild, pip, ``go build``, and similar are an open-ended, non
+    cloud-specific set, so each lives in its own package and implements this
+    one interface — the same way {@link IIgnoreStrategy} lets richer exclusion
+    live outside core. Users pass an instance via the consuming construct's
+    ``bundler`` option.
+
+    ``bundle`` runs during the owning construct's ``onSynthesize`` hook and may
+    touch the filesystem. Deferring it there keeps it skippable when the asset's
+    stack is not being synthesized, which holds as long as the hash is taken
+    over the source rather than the built output.
+
+    Bundlers compose through {@link ChainBundler} rather than a hierarchy: a
+    bundler declines (see {@link BundleResult.declined}) instead of failing when
+    it cannot run, and the chain falls through to the next.
+
+    :stability: experimental
+    '''
+
+    __jsii_type__: typing.ClassVar[str] = "cdktn.IAssetBundler"
+
+    @builtins.property
+    @jsii.member(jsii_name="bundlerKey")
+    def bundler_key(self) -> typing.Optional[builtins.str]:
+        '''(experimental) A value identifying the build, folded into the asset hash.
+
+        The source tree alone cannot see the build, so swapping a ``node:18`` base
+        image for ``node:20`` would otherwise leave identity unchanged. Under
+        ``SOURCE`` hashing this is the only channel by which the build reaches
+        identity, so it must serialize every input that can move the output, or a
+        changed build silently reuses a stale artifact. {@link BundlerKey} builds
+        one from an ordered set of parts.
+
+        Mirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be
+        summarized as a string, and fall back to ``extraHash``.
+
+        :default: - the build does not contribute to the hash
+
+        :stability: experimental
+        '''
+        return typing.cast(typing.Optional[builtins.str], jsii.get(self, "bundlerKey"))
+
+    @builtins.property
+    @jsii.member(jsii_name="outputFileName")
+    def output_file_name(self) -> typing.Optional[builtins.str]:
+        '''(experimental) The name a single-file artifact is staged under (e.g. ``archive.zip``).
+
+        A file-producing bundler (``BundleResult.file``) staged with
+        ``AssetType.FILE`` would otherwise take the source path's basename, which is
+        a directory name when the source is a directory. Declaring the name here
+        lets the artifact reflect what the bundler produces. It is static
+        configuration, needed at construction before a deferred ``SOURCE`` build
+        runs, not the file's runtime name.
+
+        Valid only for a file-producing bundler: setting it with a directory
+        packaging (anything but ``AssetType.FILE``) is rejected at construction.
+
+        :default: - the source path's basename
+
+        :stability: experimental
+        '''
+        return typing.cast(typing.Optional[builtins.str], jsii.get(self, "outputFileName"))
+
+    @jsii.member(jsii_name="bundle")
+    def bundle(
+        self,
+        *,
+        output_dir: builtins.str,
+        source: builtins.str,
+    ) -> "BundleResult":
+        '''(experimental) Produce the artifact and return a {@link BundleResult} describing it.
+
+        Implementations write into ``options.outputDir`` and never write back to
+        ``options.source``. The returned path must exist and match its declared
+        shape, or staging rejects it.
+
+        A bundler that cannot run in this environment returns
+        ``BundleResult.declined()`` so a {@link ChainBundler} can fall through to
+        the next; a thrown error is a hard failure, not a decline.
+
+        :param output_dir: (experimental) A scratch directory the bundler may write into, owned and created by the caller. The bundler produces its output here (or in a subdirectory) and returns a {@link BundleResult} pointing at the finished artifact — see {@link IAssetBundler.bundle}.
+        :param source: (experimental) Absolute path to the asset's source file or directory. The bundler reads from here and must not modify it. Exclusions (``exclude`` / ``ignoreStrategy``) are already applied: when any are configured this points at a filtered copy, not the original tree, so the bundler reads exactly the file set the asset hash was taken over.
+
+        :stability: experimental
+        '''
+        options = BundleOptions(output_dir=output_dir, source=source)
+
+        return typing.cast("BundleResult", jsii.invoke(self, "bundle", [options]))
+
+# Adding a "__jsii_proxy_class__(): typing.Type" function to the interface
+typing.cast(typing.Any, IAssetBundler).__jsii_proxy_class__ = lambda : _IAssetBundlerProxy
+
+
 @jsii.interface(jsii_type="cdktn.IAssetPackaging")
 class IAssetPackaging(typing_extensions.Protocol):
     '''(experimental) How a staged asset is produced and what shape it takes on disk.
@@ -5384,6 +5843,20 @@ class IAssetPackaging(typing_extensions.Protocol):
     :stability: experimental
     '''
 
+    @builtins.property
+    @jsii.member(jsii_name="acceptsDirectorySource")
+    def accepts_directory_source(self) -> builtins.bool:
+        '''(experimental) Whether ``pack`` accepts a directory as its ``source``.
+
+        Independent of ``producesDirectory`` and ``omitsDirectoryEntries``, both of
+        which describe the output: a ``tar.gz`` packaging takes a directory source
+        yet emits a single file. Bundler output is always a directory, so a
+        packaging that is ``false`` here cannot stage it.
+
+        :stability: experimental
+        '''
+        ...
+
     @builtins.property
     @jsii.member(jsii_name="extension")
     def extension(self) -> builtins.str:
@@ -5431,7 +5904,7 @@ class IAssetPackaging(typing_extensions.Protocol):
         target: builtins.str,
         ignore_strategy: typing.Optional["IIgnoreStrategy"] = None,
     ) -> None:
-        '''(experimental) Perform the staging transformation, writing the packaged result to ``options.target``.
+        '''(experimental) Write the packaged result to ``options.target``.
 
         :param source: (experimental) Path to the resolved (already bundled, if applicable) source.
         :param target: (experimental) Path the packaged result should be written to.
@@ -5456,6 +5929,20 @@ class _IAssetPackagingProxy:
 
     __jsii_type__: typing.ClassVar[str] = "cdktn.IAssetPackaging"
 
+    @builtins.property
+    @jsii.member(jsii_name="acceptsDirectorySource")
+    def accepts_directory_source(self) -> builtins.bool:
+        '''(experimental) Whether ``pack`` accepts a directory as its ``source``.
+
+        Independent of ``producesDirectory`` and ``omitsDirectoryEntries``, both of
+        which describe the output: a ``tar.gz`` packaging takes a directory source
+        yet emits a single file. Bundler output is always a directory, so a
+        packaging that is ``false`` here cannot stage it.
+
+        :stability: experimental
+        '''
+        return typing.cast(builtins.bool, jsii.get(self, "acceptsDirectorySource"))
+
     @builtins.property
     @jsii.member(jsii_name="extension")
     def extension(self) -> builtins.str:
@@ -5503,7 +5990,7 @@ class _IAssetPackagingProxy:
         target: builtins.str,
         ignore_strategy: typing.Optional["IIgnoreStrategy"] = None,
     ) -> None:
-        '''(experimental) Perform the staging transformation, writing the packaged result to ``options.target``.
+        '''(experimental) Write the packaged result to ``options.target``.
 
         :param source: (experimental) Path to the resolved (already bundled, if applicable) source.
         :param target: (experimental) Path the packaged result should be written to.
@@ -12231,7 +12718,7 @@ class StagedAsset:
         asset ends up — a bucket name, an object key, a URL — is resolved at
         apply time and belongs on the publisher's own reference type instead.
 
-        :param asset_hash: (experimental) A hash on the content source. This hash is used to uniquely identify this asset throughout the system. If this value doesn't change, the asset will not be rebuilt or republished.
+        :param asset_hash: (experimental) A hash on the content source, uniquely identifying this asset. The asset is not rebuilt or republished while this value is unchanged.
         :param is_directory: (experimental) Whether the staged artifact is a directory rather than a single file. Publishers branch on this to decide whether they upload one object or sync a tree; see ``IAssetPackaging.producesDirectory``.
         :param path: (experimental) The path to the staged artifact, relative to the stack directory.
 
@@ -12250,11 +12737,9 @@ class StagedAsset:
 
     @builtins.property
     def asset_hash(self) -> builtins.str:
-        '''(experimental) A hash on the content source.
+        '''(experimental) A hash on the content source, uniquely identifying this asset.
 
-        This hash is used to uniquely identify this
-        asset throughout the system. If this value doesn't change, the asset will
-        not be rebuilt or republished.
+        The asset is not rebuilt or republished while this value is unchanged.
 
         :stability: experimental
         '''
@@ -13145,6 +13630,7 @@ class TerraformAsset(
         path: builtins.str,
         asset_hash: typing.Optional[builtins.str] = None,
         asset_hash_type: typing.Optional["AssetHashType"] = None,
+        bundler: typing.Optional["IAssetBundler"] = None,
         exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
         extra_hash: typing.Optional[builtins.str] = None,
         type: typing.Optional["AssetType"] = None,
@@ -13157,7 +13643,8 @@ class TerraformAsset(
         :param id: -
         :param path: 
         :param asset_hash: 
-        :param asset_hash_type: (experimental) How the ``assetHash`` is derived. ``SOURCE`` (the default) hashes the source path. ``CUSTOM`` uses the ``assetHash`` value verbatim and requires it to be set. ``OUTPUT`` also hashes the source path today — there is no bundling step yet, so the "output" of an asset is its source verbatim — but will hash the bundler's output once bundling is introduced. If ``assetHash`` is set, this must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: AssetHashType.SOURCE
+        :param asset_hash_type: (experimental) How the ``assetHash`` is derived. ``SOURCE`` (the default) hashes the source path. ``CUSTOM`` uses the ``assetHash`` value verbatim and requires it to be set. ``OUTPUT`` hashes the source too, unless a ``bundler`` is set — then it hashes the bundler's built output, which forces an eager build (see ``bundler``). If ``assetHash`` is set, this must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: AssetHashType.SOURCE
+        :param bundler: (experimental) A bundler that builds the source into an artifact before staging. Core ships no bundler; implement ``IAssetBundler`` or use one from a bundler package. Under the default ``SOURCE`` hashing the build is deferred to synth and stays skippable; ``OUTPUT`` hashing builds eagerly to hash the artifact. The bundler's output shape must match ``type``. See ``AssetStagingOptions.bundler``. Default: - the source is staged verbatim, with no build step
         :param exclude: (experimental) Paths to exclude from the asset, relative to ``path``. See ``AssetStagingOptions.exclude`` for the accepted forms. Both the computed hash and the staged/packed content honor the exclusion. Default: - nothing is excluded
         :param extra_hash: (experimental) Extra information to fold into the hash (e.g. build instructions and other inputs). Default: - no extra hash
         :param type: 
@@ -13172,6 +13659,7 @@ class TerraformAsset(
             path=path,
             asset_hash=asset_hash,
             asset_hash_type=asset_hash_type,
+            bundler=bundler,
             exclude=exclude,
             extra_hash=extra_hash,
             type=type,
@@ -13182,11 +13670,10 @@ class TerraformAsset(
     @builtins.property
     @jsii.member(jsii_name="assetHash")
     def asset_hash(self) -> builtins.str:
-        '''(experimental) A hash of this asset, which is available at construction time.
+        '''(experimental) A hash of this asset, available at construction time.
 
-        As this is a plain string, it
-        can be used in construct IDs in order to enforce creation of a new resource when the content
-        hash has changed.
+        Being a plain string, it can be used in construct IDs to force a new
+        resource when the content hash changes.
 
         :stability: experimental
         '''
@@ -13233,6 +13720,7 @@ class TerraformAsset(
         "path": "path",
         "asset_hash": "assetHash",
         "asset_hash_type": "assetHashType",
+        "bundler": "bundler",
         "exclude": "exclude",
         "extra_hash": "extraHash",
         "type": "type",
@@ -13245,6 +13733,7 @@ class TerraformAssetConfig:
         path: builtins.str,
         asset_hash: typing.Optional[builtins.str] = None,
         asset_hash_type: typing.Optional["AssetHashType"] = None,
+        bundler: typing.Optional["IAssetBundler"] = None,
         exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
         extra_hash: typing.Optional[builtins.str] = None,
         type: typing.Optional["AssetType"] = None,
@@ -13252,7 +13741,8 @@ class TerraformAssetConfig:
         '''
         :param path: 
         :param asset_hash: 
-        :param asset_hash_type: (experimental) How the ``assetHash`` is derived. ``SOURCE`` (the default) hashes the source path. ``CUSTOM`` uses the ``assetHash`` value verbatim and requires it to be set. ``OUTPUT`` also hashes the source path today — there is no bundling step yet, so the "output" of an asset is its source verbatim — but will hash the bundler's output once bundling is introduced. If ``assetHash`` is set, this must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: AssetHashType.SOURCE
+        :param asset_hash_type: (experimental) How the ``assetHash`` is derived. ``SOURCE`` (the default) hashes the source path. ``CUSTOM`` uses the ``assetHash`` value verbatim and requires it to be set. ``OUTPUT`` hashes the source too, unless a ``bundler`` is set — then it hashes the bundler's built output, which forces an eager build (see ``bundler``). If ``assetHash`` is set, this must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: AssetHashType.SOURCE
+        :param bundler: (experimental) A bundler that builds the source into an artifact before staging. Core ships no bundler; implement ``IAssetBundler`` or use one from a bundler package. Under the default ``SOURCE`` hashing the build is deferred to synth and stays skippable; ``OUTPUT`` hashing builds eagerly to hash the artifact. The bundler's output shape must match ``type``. See ``AssetStagingOptions.bundler``. Default: - the source is staged verbatim, with no build step
         :param exclude: (experimental) Paths to exclude from the asset, relative to ``path``. See ``AssetStagingOptions.exclude`` for the accepted forms. Both the computed hash and the staged/packed content honor the exclusion. Default: - nothing is excluded
         :param extra_hash: (experimental) Extra information to fold into the hash (e.g. build instructions and other inputs). Default: - no extra hash
         :param type: 
@@ -13264,6 +13754,7 @@ class TerraformAssetConfig:
             check_type(argname="argument path", value=path, expected_type=type_hints["path"])
             check_type(argname="argument asset_hash", value=asset_hash, expected_type=type_hints["asset_hash"])
             check_type(argname="argument asset_hash_type", value=asset_hash_type, expected_type=type_hints["asset_hash_type"])
+            check_type(argname="argument bundler", value=bundler, expected_type=type_hints["bundler"])
             check_type(argname="argument exclude", value=exclude, expected_type=type_hints["exclude"])
             check_type(argname="argument extra_hash", value=extra_hash, expected_type=type_hints["extra_hash"])
             check_type(argname="argument type", value=type, expected_type=type_hints["type"])
@@ -13274,6 +13765,8 @@ class TerraformAssetConfig:
             self._values["asset_hash"] = asset_hash
         if asset_hash_type is not None:
             self._values["asset_hash_type"] = asset_hash_type
+        if bundler is not None:
+            self._values["bundler"] = bundler
         if exclude is not None:
             self._values["exclude"] = exclude
         if extra_hash is not None:
@@ -13303,10 +13796,9 @@ class TerraformAssetConfig:
         '''(experimental) How the ``assetHash`` is derived.
 
         ``SOURCE`` (the default) hashes the source path. ``CUSTOM`` uses the
-        ``assetHash`` value verbatim and requires it to be set. ``OUTPUT`` also
-        hashes the source path today — there is no bundling step yet, so the
-        "output" of an asset is its source verbatim — but will hash the
-        bundler's output once bundling is introduced.
+        ``assetHash`` value verbatim and requires it to be set. ``OUTPUT`` hashes the
+        source too, unless a ``bundler`` is set — then it hashes the bundler's
+        built output, which forces an eager build (see ``bundler``).
 
         If ``assetHash`` is set, this must be ``undefined`` or ``AssetHashType.CUSTOM``.
 
@@ -13317,6 +13809,23 @@ class TerraformAssetConfig:
         result = self._values.get("asset_hash_type")
         return typing.cast(typing.Optional["AssetHashType"], result)
 
+    @builtins.property
+    def bundler(self) -> typing.Optional["IAssetBundler"]:
+        '''(experimental) A bundler that builds the source into an artifact before staging.
+
+        Core ships no bundler; implement ``IAssetBundler`` or use one from a bundler
+        package. Under the default ``SOURCE`` hashing the build is deferred to synth
+        and stays skippable; ``OUTPUT`` hashing builds eagerly to hash the artifact.
+        The bundler's output shape must match ``type``. See
+        ``AssetStagingOptions.bundler``.
+
+        :default: - the source is staged verbatim, with no build step
+
+        :stability: experimental
+        '''
+        result = self._values.get("bundler")
+        return typing.cast(typing.Optional["IAssetBundler"], result)
+
     @builtins.property
     def exclude(self) -> typing.Optional[typing.List[builtins.str]]:
         '''(experimental) Paths to exclude from the asset, relative to ``path``.
@@ -19831,23 +20340,14 @@ class AssetStaging(
     metaclass=jsii.JSIIMeta,
     jsii_type="cdktn.AssetStaging",
 ):
-    '''(experimental) Resolves an asset's identity (``SOURCE``/``OUTPUT``/``CUSTOM`` hashing, with ``exclude``/``extraHash``) and stages it to disk.
+    '''(experimental) Resolves an asset's identity and stages its content to disk.
 
-    Hashing happens eagerly in the constructor; staging the content to
-    ``targetPath`` only happens when ``stage()`` is called, which callers do from
-    their own ``onSynthesize`` hook. This keeps the filesystem side effect in the
-    one window where it is safe to run, and keeps this class skippable once a
-    bundler is introduced.
-
-    ``SOURCE`` and ``OUTPUT`` compute identically here: without a bundler, the
-    "output" of an asset is its source verbatim. A future bundler changes what
-    ``OUTPUT`` hashes, not this class.
-
-    The source-tree walk behind ``SOURCE``/``OUTPUT`` is cached per synth (see
-    {@link hashCachesByRoot}), so referencing the same asset from more than one
-    resource or stack hashes it once. ``ASSET_HASH_SALT_CONTEXT_KEY`` folds an
-    app-wide value into every computed hash, for bulk cache-busting across an
-    entire tree rather than one asset's ``extraHash``.
+    The hash is available immediately after construction; the filesystem write
+    is deferred to ``stage()``, the one window where it is safe. Hashing is
+    cached per synth (see {@link hashCachesByRoot}) so an asset referenced from
+    several places is walked once. Without a bundler, ``SOURCE`` and ``OUTPUT`` both
+    hash the source; with one they diverge, as ``AssetStagingOptions.bundler``
+    describes.
 
     :stability: experimental
     '''
@@ -19859,6 +20359,8 @@ class AssetStaging(
         *,
         packaging: "IAssetPackaging",
         source_path: builtins.str,
+        bundler: typing.Optional["IAssetBundler"] = None,
+        display_name: typing.Optional[builtins.str] = None,
         exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
         extra_hash: typing.Optional[builtins.str] = None,
         ignore_strategy: typing.Optional["IIgnoreStrategy"] = None,
@@ -19870,10 +20372,12 @@ class AssetStaging(
         :param id: -
         :param packaging: (experimental) How the staged result is produced and shaped. The caller decides this (e.g. from its own ``AssetType``) — ``AssetStaging`` never infers or changes it based on ``exclude``/``extraHash``.
         :param source_path: (experimental) Absolute path to the source file or directory. Resolving a relative path against ``cdktf.json`` is the caller's responsibility.
+        :param bundler: (experimental) A bundler that builds the source into an artifact before staging. Under the default ``SOURCE`` hashing the build is deferred to ``stage()`` and stays skippable; ``OUTPUT`` hashing builds eagerly at construction time to hash the artifact, forgoing skippability. The bundler's declared output shape must match the packaging: a ``BundleResult.directory`` needs a directory-accepting packaging, a ``BundleResult.file`` a single-file one (``AssetType.FILE``). The mismatch is caught once the build runs. Default: - the source is staged verbatim, with no build step
+        :param display_name: (experimental) Identifier used in error messages, so they name the user-facing construct (e.g. the ``TerraformAsset``) rather than this internal staging child. Default: - the staging construct's own id
         :param exclude: (experimental) Paths to exclude, relative to ``sourcePath``. Cannot be combined with ``ignoreStrategy``, which replaces this matcher rather than layering on top of it. Default: - nothing is excluded
         :param extra_hash: (experimental) Extra information to fold into the hash (e.g. build instructions and other inputs). Default: - no extra hash
         :param ignore_strategy: (experimental) Exclusion matching, for callers that need ``.gitignore`` / ``.dockerignore`` parity rather than the built-in exact-path / suffix / directory matcher. Default: - ``exclude`` is used with the built-in matcher
-        :param asset_hash: (experimental) Specify a custom hash for this asset. If ``assetHashType`` is set it must be set to ``AssetHashType.CUSTOM``. The value is used verbatim as the asset hash, and because it names the staged asset file it may only contain letters, digits, ``_``, ``.`` and ``-``. NOTE: the hash is used in order to identify a specific revision of the asset, and used for optimizing and caching deployment activities related to this asset such as packaging, uploading to cloud storage, etc. If you chose to customize the hash, you will need to make sure it is updated every time the asset changes, or otherwise it is possible that some deployments will not be invalidated. Default: - based on ``assetHashType``
+        :param asset_hash: (experimental) Specify a custom hash for this asset. If ``assetHashType`` is set it must be set to ``AssetHashType.CUSTOM``. The value is used verbatim as the asset hash, and because it names the staged asset file it may only contain letters, digits, ``_``, ``.`` and ``-``. The hash identifies a specific revision of the asset and caches deployment work (packaging, uploading). A custom hash must be updated whenever the asset changes, or some deployments will not be invalidated. Default: - based on ``assetHashType``
         :param asset_hash_type: (experimental) Specifies the type of hash to calculate for this asset. If ``assetHash`` is configured, this option must be ``undefined`` or ``AssetHashType.CUSTOM``. Default: - the default is ``AssetHashType.SOURCE``, but if ``assetHash`` is explicitly specified this value defaults to ``AssetHashType.CUSTOM``.
 
         :stability: experimental
@@ -19885,6 +20389,8 @@ class AssetStaging(
         props = AssetStagingOptions(
             packaging=packaging,
             source_path=source_path,
+            bundler=bundler,
+            display_name=display_name,
             exclude=exclude,
             extra_hash=extra_hash,
             ignore_strategy=ignore_strategy,
@@ -19896,12 +20402,13 @@ class AssetStaging(
 
     @jsii.member(jsii_name="stage")
     def stage(self, target_path: builtins.str) -> None:
-        '''(experimental) Write the staged content to ``targetPath``.
+        '''(experimental) Stage the asset's content to ``targetPath``.
 
-        Called from the owning
-        construct's ``onSynthesize`` hook, once the target path is known.
+        Called from the owning construct's ``onSynthesize`` hook. Without a bundler
+        the source is packaged verbatim; with one, the bundler's output is, built
+        eagerly for ``OUTPUT`` hashing or deferred to here for ``SOURCE``.
 
-        :param target_path: - path the packaged result should be written to.
+        :param target_path: -
 
         :stability: experimental
         '''
@@ -19913,11 +20420,10 @@ class AssetStaging(
     @builtins.property
     @jsii.member(jsii_name="assetHash")
     def asset_hash(self) -> builtins.str:
-        '''(experimental) A hash of this asset, which is available at construction time.
+        '''(experimental) A hash of this asset, available at construction time.
 
-        As this is a plain string, it
-        can be used in construct IDs in order to enforce creation of a new resource when the content
-        hash has changed.
+        Being a plain string, it can be used in construct IDs to force a new
+        resource when the content hash changes.
 
         :stability: experimental
         '''
@@ -20257,6 +20763,111 @@ class BooleanMapMap(metaclass=jsii.JSIIMeta, jsii_type="cdktn.BooleanMapMap"):
         jsii.set(self, "terraformResource", value) # pyright: ignore[reportArgumentType]
 
 
+@jsii.implements(IAssetBundler)
+class ChainBundler(metaclass=jsii.JSIIMeta, jsii_type="cdktn.ChainBundler"):
+    '''(experimental) Composes bundlers into a "try each in order until one runs" chain.
+
+    This is how a local bundler and a Docker bundler compose without being
+    rewritten as one: each leg declines (``BundleResult.declined()``) when it
+    cannot run here, and the chain moves to the next. The first non-declining
+    result wins; if all decline, ``bundle`` throws, since staging has nothing to
+    fall back to. Each leg builds into its own output directory, so a leg that
+    writes before declining cannot leak partial files into the leg that wins.
+
+    The chain's ``bundlerKey`` folds in *every* leg's key, so identity is the same
+    regardless of which leg ends up running — a build that could have gone local
+    or Docker is one asset, not two.
+
+    This makes the legs interchangeable only if they produce equivalent output.
+    Under ``SOURCE`` hashing they must: a machine with a host tool and one without
+    run different legs, and non-equivalent legs would stage different bytes under
+    the same hash. Use ``OUTPUT`` hashing when legs may diverge, so identity tracks
+    the artifact each leg actually produced.
+
+    :stability: experimental
+    '''
+
+    @jsii.member(jsii_name="of")
+    @builtins.classmethod
+    def of(cls, *bundlers: "IAssetBundler") -> "ChainBundler":
+        '''(experimental) Chain bundlers in the order given;
+
+        earlier bundlers are preferred.
+
+        :param bundlers: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = cached_type_hints(_typecheckingstub__f90bbf7276852d6eae454e98f7945b00bbfa6b5451b7f6bda28e77371cec3e96)
+            check_type(argname="argument bundlers", value=bundlers, expected_type=typing.Tuple[type_hints["bundlers"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast("ChainBundler", jsii.sinvoke(cls, "of", [*bundlers]))
+
+    @jsii.member(jsii_name="bundle")
+    def bundle(
+        self,
+        *,
+        output_dir: builtins.str,
+        source: builtins.str,
+    ) -> "BundleResult":
+        '''(experimental) Produce the artifact and return a {@link BundleResult} describing it.
+
+        Implementations write into ``options.outputDir`` and never write back to
+        ``options.source``. The returned path must exist and match its declared
+        shape, or staging rejects it.
+
+        A bundler that cannot run in this environment returns
+        ``BundleResult.declined()`` so a {@link ChainBundler} can fall through to
+        the next; a thrown error is a hard failure, not a decline.
+
+        :param output_dir: (experimental) A scratch directory the bundler may write into, owned and created by the caller. The bundler produces its output here (or in a subdirectory) and returns a {@link BundleResult} pointing at the finished artifact — see {@link IAssetBundler.bundle}.
+        :param source: (experimental) Absolute path to the asset's source file or directory. The bundler reads from here and must not modify it. Exclusions (``exclude`` / ``ignoreStrategy``) are already applied: when any are configured this points at a filtered copy, not the original tree, so the bundler reads exactly the file set the asset hash was taken over.
+
+        :stability: experimental
+        '''
+        options = BundleOptions(output_dir=output_dir, source=source)
+
+        return typing.cast("BundleResult", jsii.invoke(self, "bundle", [options]))
+
+    @builtins.property
+    @jsii.member(jsii_name="bundlerKey")
+    def bundler_key(self) -> typing.Optional[builtins.str]:
+        '''(experimental) A value identifying the build, folded into the asset hash.
+
+        The source tree alone cannot see the build, so swapping a ``node:18`` base
+        image for ``node:20`` would otherwise leave identity unchanged. Under
+        ``SOURCE`` hashing this is the only channel by which the build reaches
+        identity, so it must serialize every input that can move the output, or a
+        changed build silently reuses a stale artifact. {@link BundlerKey} builds
+        one from an ordered set of parts.
+
+        Mirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be
+        summarized as a string, and fall back to ``extraHash``.
+
+        :stability: experimental
+        '''
+        return typing.cast(typing.Optional[builtins.str], jsii.get(self, "bundlerKey"))
+
+    @builtins.property
+    @jsii.member(jsii_name="outputFileName")
+    def output_file_name(self) -> typing.Optional[builtins.str]:
+        '''(experimental) The name a single-file artifact is staged under (e.g. ``archive.zip``).
+
+        A file-producing bundler (``BundleResult.file``) staged with
+        ``AssetType.FILE`` would otherwise take the source path's basename, which is
+        a directory name when the source is a directory. Declaring the name here
+        lets the artifact reflect what the bundler produces. It is static
+        configuration, needed at construction before a deferred ``SOURCE`` build
+        runs, not the file's runtime name.
+
+        Valid only for a file-producing bundler: setting it with a directory
+        packaging (anything but ``AssetType.FILE``) is rejected at construction.
+
+        :stability: experimental
+        '''
+        return typing.cast(typing.Optional[builtins.str], jsii.get(self, "outputFileName"))
+
+
 @jsii.implements(IInterpolatingParent, IResolvable, ITerraformAddressable)
 class ComplexComputedList(
     metaclass=jsii.JSIIMeta,
@@ -29244,6 +29855,11 @@ __all__ = [
     "BooleanMap",
     "BooleanMapList",
     "BooleanMapMap",
+    "BundleOptions",
+    "BundleOutputType",
+    "BundleResult",
+    "BundlerKey",
+    "ChainBundler",
     "CloudBackend",
     "CloudBackendConfig",
     "CloudWorkspace",
@@ -29295,6 +29911,7 @@ __all__ = [
     "IAnyProducer",
     "IAspect",
     "IAsset",
+    "IAssetBundler",
     "IAssetPackaging",
     "IFragmentConcatenator",
     "IIgnoreStrategy",
@@ -29555,6 +30172,8 @@ def _typecheckingstub__5026244ff290924dad88f65421d8025b8bcb105d693dec43cd93a0c7d
     asset_hash_type: typing.Optional[AssetHashType] = None,
     packaging: IAssetPackaging,
     source_path: builtins.str,
+    bundler: typing.Optional[IAssetBundler] = None,
+    display_name: typing.Optional[builtins.str] = None,
     exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
     extra_hash: typing.Optional[builtins.str] = None,
     ignore_strategy: typing.Optional[IIgnoreStrategy] = None,
@@ -29593,6 +30212,44 @@ def _typecheckingstub__912173407c419eae209032e0ac104680f082bb5aad4825d0e858e8efc
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__e4984c7b158b6fd9f304d19bf1be6b525991aa5c57db01aa1dd6d282c3369f9e(
+    *,
+    output_dir: builtins.str,
+    source: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__cb448e5d937b8e66717fe97ab740ea1924edd313428fa2e65c41a3f2d7c1a24c(
+    path: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__e6adf0d1d61dee6269a50f7bde47aef784df796b53286fb04ab6c071a75d6975(
+    path: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__76b2ba8d3e61fcbea83025fd36866ed49e2970a52cbe09f43be16a01cf5a6858(
+    *parts: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__5542e2e8a7f529585fff07dcaf5ca7a0425baa3a9af1286723c0b3fb21d976c6(
+    *parts: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__89d2ee0220c33c5357157d502001eb29e4d7acc5dd0985be2aeb7f269d3ef50b(
+    entries: typing.Mapping[builtins.str, builtins.str],
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__4c43a277c741c97005cffe2a27390aad01d95fded1b13c16a35f07ccaec84f7a(
     *,
     organization: builtins.str,
@@ -31530,6 +32187,7 @@ def _typecheckingstub__6f29998a5dacee0da3977e8d51379662670eb6942990ac7e6e052ab5e
     path: builtins.str,
     asset_hash: typing.Optional[builtins.str] = None,
     asset_hash_type: typing.Optional[AssetHashType] = None,
+    bundler: typing.Optional[IAssetBundler] = None,
     exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
     extra_hash: typing.Optional[builtins.str] = None,
     type: typing.Optional[AssetType] = None,
@@ -31548,6 +32206,7 @@ def _typecheckingstub__e7a613b39a707470fb3fa76a5d5d750aa8285bec8b92786190d69d5b7
     path: builtins.str,
     asset_hash: typing.Optional[builtins.str] = None,
     asset_hash_type: typing.Optional[AssetHashType] = None,
+    bundler: typing.Optional[IAssetBundler] = None,
     exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
     extra_hash: typing.Optional[builtins.str] = None,
     type: typing.Optional[AssetType] = None,
@@ -32940,6 +33599,8 @@ def _typecheckingstub__a694062800c2f527dfda0d5a21ceaa0607085c2bef7277ea0a3217058
     *,
     packaging: IAssetPackaging,
     source_path: builtins.str,
+    bundler: typing.Optional[IAssetBundler] = None,
+    display_name: typing.Optional[builtins.str] = None,
     exclude: typing.Optional[typing.Sequence[builtins.str]] = None,
     extra_hash: typing.Optional[builtins.str] = None,
     ignore_strategy: typing.Optional[IIgnoreStrategy] = None,
@@ -33049,6 +33710,12 @@ def _typecheckingstub__fc66bb069d4f417396a421b3c709177b54ebf2b757f3965e92709f83a
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__f90bbf7276852d6eae454e98f7945b00bbfa6b5451b7f6bda28e77371cec3e96(
+    *bundlers: IAssetBundler,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__383f75d3115cefe50368b79b9cef65b6997c768310bb192c74f470cf288d8b78(
     terraform_resource: IInterpolatingParent,
     terraform_attribute: builtins.str,
@@ -34874,5 +35541,5 @@ def _typecheckingstub__0930e68f78776f6767a34b896806a2c7f0841f069ff5f5b3f5b121add
     """Type checking stubs"""
     pass
 
-for cls in [IAnyProducer, IAspect, IAsset, IAssetPackaging, IFragmentConcatenator, IIgnoreStrategy, IImportableConfig, IInterpolatingParent, IListProducer, IManifest, INumberProducer, IPostProcessor, IRemoteWorkspace, IResolvable, IResolveContext, IResource, IResourceConstructor, IScopeCallback, IStackSynthesizer, IStringProducer, ISynthesisSession, ITerraformAddressable, ITerraformDependable, ITerraformEphemeralResource, ITerraformIterator, ITerraformResource, ITokenMapper, ITokenResolver]:
+for cls in [IAnyProducer, IAspect, IAsset, IAssetBundler, IAssetPackaging, IFragmentConcatenator, IIgnoreStrategy, IImportableConfig, IInterpolatingParent, IListProducer, IManifest, INumberProducer, IPostProcessor, IRemoteWorkspace, IResolvable, IResolveContext, IResource, IResourceConstructor, IScopeCallback, IStackSynthesizer, IStringProducer, ISynthesisSession, ITerraformAddressable, ITerraformDependable, ITerraformEphemeralResource, ITerraformIterator, ITerraformResource, ITokenMapper, ITokenResolver]:
     typing.cast(typing.Any, cls).__protocol_attrs__ = typing.cast(typing.Any, cls).__protocol_attrs__ - set(['__jsii_proxy_class__', '__jsii_type__'])

{cdktn-0.25.0.dev38 → cdktn-0.25.0.dev40}/src/cdktn/_jsii/__init__.py

@@ -21,7 +21,7 @@ _SUBMODULE_FQN_MAP = {
 }
 
 __jsii_assembly__ = jsii.JSIIAssembly.load(
-    "cdktn", "0.25.0-pre.38", __name__[0:-6], "cdktn@0.25.0-pre.38.jsii.tgz"
+    "cdktn", "0.25.0-pre.40", __name__[0:-6], "cdktn@0.25.0-pre.40.jsii.tgz"
 )
 
 __all__ = [

{cdktn-0.25.0.dev38 → cdktn-0.25.0.dev40/src/cdktn.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cdktn
-Version: 0.25.0.dev38
+Version: 0.25.0.dev40
 Summary: Cloud Development Kit for Terraform
 Home-page: https://github.com/open-constructs/cdk-terrain
 Author: OpenConstructs

{cdktn-0.25.0.dev38 → cdktn-0.25.0.dev40}/src/cdktn.egg-info/SOURCES.txt

@@ -11,5 +11,5 @@ src/cdktn.egg-info/dependency_links.txt
 src/cdktn.egg-info/requires.txt
 src/cdktn.egg-info/top_level.txt
 src/cdktn/_jsii/__init__.py
-src/cdktn/_jsii/cdktn@0.25.0-pre.38.jsii.tgz
+src/cdktn/_jsii/cdktn@0.25.0-pre.40.jsii.tgz
 src/cdktn/testing_matchers/__init__.py