cdktn 0.25.0.dev38__tar.gz → 0.25.0.dev39__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cdktn
-Version: 0.25.0.dev38
+Version: 0.25.0.dev39
 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.dev39}/setup.py

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

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

@@ -790,6 +790,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,6 +805,8 @@ 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,
@@ -813,6 +817,8 @@ class AssetStagingOptions(AssetOptions):
         :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 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 +831,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 +844,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:
@@ -909,6 +921,33 @@ 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. A bundler always produces a
+        directory, so single-file packaging (``AssetType.FILE``) is rejected.
+
+        :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 +1494,146 @@ 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 the directory that holds 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 the directory that holds 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()
+        )
+
+
+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).
+
+    :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=[],
@@ -5371,6 +5550,138 @@ 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 set that
+    is not cloud-specific, 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.
+
+    ``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.
+
+    :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. 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.
+
+        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
+        '''
+        ...
+
+    @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.
+
+        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.
+
+        :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 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 set that
+    is not cloud-specific, 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.
+
+    ``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.
+
+    :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. 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.
+
+        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"))
+
+    @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.
+
+        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.
+
+        :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 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]))
+
+# 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 +5695,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 +5756,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 +5781,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 +5842,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.
@@ -13145,6 +13484,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 +13497,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. ``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 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 +13513,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,
@@ -13233,6 +13575,7 @@ class TerraformAsset(
         "path": "path",
         "asset_hash": "assetHash",
         "asset_hash_type": "assetHashType",
+        "bundler": "bundler",
         "exclude": "exclude",
         "extra_hash": "extraHash",
         "type": "type",
@@ -13245,6 +13588,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 +13596,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. ``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 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 +13609,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 +13620,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 +13651,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 +13664,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.
+        ``AssetType.FILE`` is rejected, since bundler output is always a directory.
+        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 +20195,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 +20214,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,6 +20227,8 @@ 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 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
@@ -19885,6 +20244,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 +20257,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
         '''
@@ -29244,6 +29606,8 @@ __all__ = [
     "BooleanMap",
     "BooleanMapList",
     "BooleanMapMap",
+    "BundleOptions",
+    "BundlerKey",
     "CloudBackend",
     "CloudBackendConfig",
     "CloudWorkspace",
@@ -29295,6 +29659,7 @@ __all__ = [
     "IAnyProducer",
     "IAspect",
     "IAsset",
+    "IAssetBundler",
     "IAssetPackaging",
     "IFragmentConcatenator",
     "IIgnoreStrategy",
@@ -29555,6 +29920,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 +29960,32 @@ def _typecheckingstub__912173407c419eae209032e0ac104680f082bb5aad4825d0e858e8efc
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__e4984c7b158b6fd9f304d19bf1be6b525991aa5c57db01aa1dd6d282c3369f9e(
+    *,
+    output_dir: builtins.str,
+    source: 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 +31923,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 +31942,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 +33335,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,
@@ -34874,5 +35271,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.dev39}/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.39", __name__[0:-6], "cdktn@0.25.0-pre.39.jsii.tgz"
 )
 
 __all__ = [

{cdktn-0.25.0.dev38 → cdktn-0.25.0.dev39/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.dev39
 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.dev39}/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.39.jsii.tgz
 src/cdktn/testing_matchers/__init__.py