cdktn 0.25.0.dev39__tar.gz → 0.25.0.dev40__tar.gz

{cdktn-0.25.0.dev39/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.dev39
+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.dev39 → cdktn-0.25.0.dev40}/setup.py

@@ -5,7 +5,7 @@ kwargs = json.loads(
     """
 {
     "name": "cdktn",
-    "version": "0.25.0.dev39",
+    "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.39.jsii.tgz"
+            "cdktn@0.25.0-pre.40.jsii.tgz"
         ],
         "cdktn": [
             "py.typed"

{cdktn-0.25.0.dev39 → 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``
 
@@ -813,11 +809,11 @@ class AssetStagingOptions(AssetOptions):
     ) -> 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. A bundler always produces a directory, so single-file packaging (``AssetType.FILE``) is rejected. Default: - the source is staged verbatim, with no build step
+        :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
@@ -864,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``
 
@@ -927,8 +921,10 @@ class AssetStagingOptions(AssetOptions):
 
         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. A bundler always produces a
-        directory, so single-file packaging (``AssetType.FILE``) is rejected.
+        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
 
@@ -1507,7 +1503,7 @@ class BundleOptions:
         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 the directory that holds the finished artifact — see {@link IAssetBundler.bundle}.
+        :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
@@ -1526,7 +1522,7 @@ class BundleOptions:
         '''(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 the directory that holds the finished artifact — see
+        returns a {@link BundleResult} pointing at the finished artifact — see
         {@link IAssetBundler.bundle}.
 
         :stability: experimental
@@ -1561,15 +1557,115 @@ class BundleOptions:
         )
 
 
+@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 where it appears in a value, so distinct
-    inputs can never collide into the same key (``["a:b", "c"]`` and
-    ``["a", "b:c"]`` stay different).
+    with a separator that is escaped inside values, so distinct inputs cannot
+    collide into the same key.
 
     :stability: experimental
 
@@ -5514,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
         '''
@@ -5536,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
         '''
@@ -5555,19 +5649,21 @@ 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 set that
-    is not cloud-specific, so each lives in its own package and implements this
+    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 without core taking on a glob parser. A third party
-    develops a bundler by implementing this interface and publishing it as a
-    package; users pass an instance via the consuming construct's ``bundler``
-    option.
+    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
     '''
 
@@ -5577,14 +5673,11 @@ class IAssetBundler(typing_extensions.Protocol):
         '''(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. A value
-        capturing the build (e.g. ``docker:<image>:<command>``) closes that gap.
-
-        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 —
-        base image, command, tool version, environment, arguments. Anything left
-        out means a changed build silently reuses a stale artifact. {@link * BundlerKey} builds one from an ordered set of parts so the format is not
-        reinvented per bundler.
+        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``.
@@ -5595,17 +5688,45 @@ class IAssetBundler(typing_extensions.Protocol):
         '''
         ...
 
+    @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) -> builtins.str:
-        '''(experimental) Produce the artifact and return the directory holding it.
+    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 return it or a
-        subdirectory, never writing back to ``options.source``. The returned
-        directory is then packaged as an unbundled source directory would be.
-        Returning a file, or a path that does not exist, is rejected — the
-        contract is a directory, and packaging always treats the result as one.
+        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.
 
-        :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 the directory that holds the finished artifact — see {@link IAssetBundler.bundle}.
+        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
@@ -5617,19 +5738,21 @@ 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 set that
-    is not cloud-specific, so each lives in its own package and implements this
+    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 without core taking on a glob parser. A third party
-    develops a bundler by implementing this interface and publishing it as a
-    package; users pass an instance via the consuming construct's ``bundler``
-    option.
+    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
     '''
 
@@ -5641,14 +5764,11 @@ class _IAssetBundlerProxy:
         '''(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. A value
-        capturing the build (e.g. ``docker:<image>:<command>``) closes that gap.
-
-        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 —
-        base image, command, tool version, environment, arguments. Anything left
-        out means a changed build silently reuses a stale artifact. {@link * BundlerKey} builds one from an ordered set of parts so the format is not
-        reinvented per bundler.
+        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``.
@@ -5659,24 +5779,52 @@ class _IAssetBundlerProxy:
         '''
         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) -> builtins.str:
-        '''(experimental) Produce the artifact and return the directory holding it.
+    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.
 
-        Implementations write into ``options.outputDir`` and return it or a
-        subdirectory, never writing back to ``options.source``. The returned
-        directory is then packaged as an unbundled source directory would be.
-        Returning a file, or a path that does not exist, is rejected — the
-        contract is a directory, and packaging always treats the result as one.
+        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 the directory that holds the finished artifact — see {@link IAssetBundler.bundle}.
+        :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(builtins.str, jsii.invoke(self, "bundle", [options]))
+        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
@@ -12570,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.
 
@@ -12589,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
         '''
@@ -13498,7 +13644,7 @@ class TerraformAsset(
         :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`` 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. ``AssetType.FILE`` is rejected, since bundler output is always a directory. See ``AssetStagingOptions.bundler``. Default: - the source is staged verbatim, with no build step
+        :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: 
@@ -13524,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
         '''
@@ -13597,7 +13742,7 @@ 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`` 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. ``AssetType.FILE`` is rejected, since bundler output is always a directory. See ``AssetStagingOptions.bundler``. Default: - the source is staged verbatim, with no build step
+        :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: 
@@ -13671,8 +13816,8 @@ class TerraformAssetConfig:
         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.
-        ``AssetType.FILE`` is rejected, since bundler output is always a directory.
-        See ``AssetStagingOptions.bundler``.
+        The bundler's output shape must match ``type``. See
+        ``AssetStagingOptions.bundler``.
 
         :default: - the source is staged verbatim, with no build step
 
@@ -20227,12 +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. A bundler always produces a directory, so single-file packaging (``AssetType.FILE``) is rejected. Default: - the source is staged verbatim, with no build step
+        :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
@@ -20275,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
         '''
@@ -20619,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,
@@ -29607,7 +29856,10 @@ __all__ = [
     "BooleanMapList",
     "BooleanMapMap",
     "BundleOptions",
+    "BundleOutputType",
+    "BundleResult",
     "BundlerKey",
+    "ChainBundler",
     "CloudBackend",
     "CloudBackendConfig",
     "CloudWorkspace",
@@ -29968,6 +30220,18 @@ def _typecheckingstub__e4984c7b158b6fd9f304d19bf1be6b525991aa5c57db01aa1dd6d282c
     """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:
@@ -33446,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,

{cdktn-0.25.0.dev39 → 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.39", __name__[0:-6], "cdktn@0.25.0-pre.39.jsii.tgz"
+    "cdktn", "0.25.0-pre.40", __name__[0:-6], "cdktn@0.25.0-pre.40.jsii.tgz"
 )
 
 __all__ = [

{cdktn-0.25.0.dev39 → 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.dev39
+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.dev39 → 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.39.jsii.tgz
+src/cdktn/_jsii/cdktn@0.25.0-pre.40.jsii.tgz
 src/cdktn/testing_matchers/__init__.py