cdktn 0.25.0-pre.9 → 0.25.0

package/README.md

@@ -3,6 +3,18 @@
 cdktn is a framework for defining cloud infrastructure using Terraform providers and modules. It allows for
 users to define infrastructure resources using higher-level programming languages.
 
+CDK Terrain (CDKTN) is the community-maintained successor to CDK for Terraform (CDKTF). Migrating from CDKTF? Follow the [migration guide](https://cdktn.io/docs/release/upgrade-guide-v0-22).
+
+## Use with AI agents
+
+The CDKTN docs are served to AI coding agents by a hosted [MCP server](https://cdktn.io/docs/ai-agents) at `https://cdktn.io/docs/mcp` (streamable HTTP, no auth). Point your agent at it rather than relying on prior CDKTF knowledge:
+
+```bash
+claude mcp add --transport http cdktn https://cdktn.io/docs/mcp
+```
+
+An [agent skill](https://cdktn.io/docs/skill.md) and an [llms.txt index](https://cdktn.io/llms.txt) are also available.
+
 ## Build
 
 Install dependencies

package/lib/annotations.js

@@ -14,7 +14,7 @@ exports.DISABLE_STACK_TRACE_IN_METADATA = "@cdktf/disable_stack_trace_in_metadat
  */
 class Annotations {
     scope;
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Annotations", version: "0.25.0-pre.9" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Annotations", version: "0.25.0" };
     /**
      * Returns the annotations API for a construct scope.
      * @param scope The scope

package/lib/app.js

@@ -51,7 +51,7 @@ exports.CONTEXT_ENV = "CDKTF_CONTEXT_JSON";
  * Represents a cdktn application.
  */
 class App extends constructs_1.Construct {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.App", version: "0.25.0-pre.9" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.App", version: "0.25.0" };
     /**
      * The output directory into which resources will be synthesized.
      */

package/lib/aspect.js

@@ -8,7 +8,7 @@ const ASPECTS_SYMBOL = Symbol("cdktf-aspects");
  * synthesis.
  */
 class Aspects {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Aspects", version: "0.25.0-pre.9" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Aspects", version: "0.25.0" };
     /**
      * Returns the `Aspects` object associated with a construct scope.
      * @param scope The scope for which these aspects will apply.

package/lib/asset-hash.d.ts

@@ -0,0 +1,75 @@
+import { IIgnoreStrategy } from "./ignore-strategy";
+/**
+ * Options for {@link AssetHash.of}.
+ */
+export interface AssetHashOptions {
+    /**
+     * Paths to exclude, relative to the hashed path. Cannot be combined with
+     * `ignoreStrategy`, which replaces this matcher rather than layering on
+     * top of it.
+     *
+     * @default - nothing is excluded
+     */
+    readonly exclude?: string[];
+    /**
+     * Extra information to fold into the hash.
+     *
+     * @default - no extra data
+     */
+    readonly extraHash?: string;
+    /**
+     * 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
+     */
+    readonly ignoreStrategy?: IIgnoreStrategy;
+}
+/**
+ * Computes a content hash of a file or directory without staging it.
+ *
+ * Providers that read a local path directly — a Docker build `context`, for
+ * example — need a content hash to drive `triggers`, but have no use for a
+ * staged copy of the source. `Asset` and `TerraformAsset` always produce a
+ * staged copy; this is the identity half without the staging half.
+ */
+export declare class AssetHash {
+    /**
+     * Content hash of a file or directory, without staging it.
+     *
+     * This is a hash of the source tree, and it does not depend on how the
+     * source is later packaged. `hashPath` is always called with `archive`
+     * unset, so directory records are part of the digest; the hash of a given
+     * tree is therefore the same whether it is later copied, zipped, or packed
+     * by a custom `IAssetPackaging` such as `tar.bz2`.
+     *
+     * A consequence worth stating: this does not equal
+     * `TerraformAsset(dir, { type: ARCHIVE }).assetHash` for a directory with
+     * subdirectories. That asset frames its hash to the emitted ZIP, which has
+     * no directory entries (see #323), so directory-only changes move it and
+     * not this. It equals a `FILE` / `DIRECTORY` `TerraformAsset` hash only
+     * when the `canonicalAssetHashes` flag is enabled, since that flag is what
+     * puts the asset on this same canonical scheme.
+     *
+     * A relative `filePath` is resolved against the directory containing
+     * `cdktf.json`, the same base `TerraformAsset` uses, so both hash the same
+     * source regardless of the process working directory. Absolute paths are
+     * used as-is. Throws if `filePath` is relative and no `cdktf.json` is found
+     * above the working directory.
+     * @param filePath - path to a file or directory to hash
+     * @param options - see {@link AssetHashOptions}
+     */
+    static of(filePath: string, options?: AssetHashOptions): string;
+    /**
+     * Resolve `filePath` to an absolute path using the same base as
+     * `TerraformAsset`: relative paths are anchored to the directory holding
+     * `cdktf.json`, not `process.cwd()`, so a hash taken here matches the one
+     * `TerraformAsset` computes for the same source even when the app is run
+     * from a subdirectory or a test runner. Unlike `TerraformAsset`, there is
+     * no construct scope to read the `cdktfJsonPath` context from, so this uses
+     * the `findFileAboveCwd` fallback directly.
+     * @param filePath - path passed to {@link AssetHash.of}
+     */
+    private static resolvePath;
+    private constructor();
+}

package/lib/asset-hash.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetHash = void 0;
+const JSII_RTTI_SYMBOL_1 = Symbol.for("jsii.rtti");
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+const crypto = __importStar(require("crypto"));
+const path = __importStar(require("path"));
+const fs_1 = require("./private/fs");
+const ignore_strategy_1 = require("./ignore-strategy");
+const errors_1 = require("./errors");
+/**
+ * Computes a content hash of a file or directory without staging it.
+ *
+ * Providers that read a local path directly — a Docker build `context`, for
+ * example — need a content hash to drive `triggers`, but have no use for a
+ * staged copy of the source. `Asset` and `TerraformAsset` always produce a
+ * staged copy; this is the identity half without the staging half.
+ */
+class AssetHash {
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.AssetHash", version: "0.25.0" };
+    /**
+     * Content hash of a file or directory, without staging it.
+     *
+     * This is a hash of the source tree, and it does not depend on how the
+     * source is later packaged. `hashPath` is always called with `archive`
+     * unset, so directory records are part of the digest; the hash of a given
+     * tree is therefore the same whether it is later copied, zipped, or packed
+     * by a custom `IAssetPackaging` such as `tar.bz2`.
+     *
+     * A consequence worth stating: this does not equal
+     * `TerraformAsset(dir, { type: ARCHIVE }).assetHash` for a directory with
+     * subdirectories. That asset frames its hash to the emitted ZIP, which has
+     * no directory entries (see #323), so directory-only changes move it and
+     * not this. It equals a `FILE` / `DIRECTORY` `TerraformAsset` hash only
+     * when the `canonicalAssetHashes` flag is enabled, since that flag is what
+     * puts the asset on this same canonical scheme.
+     *
+     * A relative `filePath` is resolved against the directory containing
+     * `cdktf.json`, the same base `TerraformAsset` uses, so both hash the same
+     * source regardless of the process working directory. Absolute paths are
+     * used as-is. Throws if `filePath` is relative and no `cdktf.json` is found
+     * above the working directory.
+     * @param filePath - path to a file or directory to hash
+     * @param options - see {@link AssetHashOptions}
+     */
+    static of(filePath, options = {}) {
+        if (options.exclude?.length && options.ignoreStrategy) {
+            throw (0, errors_1.assetHashConflictingExcludeOptions)();
+        }
+        const resolved = AssetHash.resolvePath(filePath);
+        const strategy = options.ignoreStrategy ??
+            new ignore_strategy_1.ExcludeIgnoreStrategy(options.exclude ?? []);
+        // Pinned to the canonical scheme: this is a brand-new API with no
+        // existing hashes to preserve, so it has no reason to start on the
+        // legacy scheme that `canonicalAssetHashes` exists to move away from.
+        const baseHash = (0, fs_1.hashPath)(resolved, {
+            canonical: true,
+            shouldExclude: (relativePath, isDirectory) => strategy.ignores({ relativePath, isDirectory }),
+            descendIntoExcludedDirectories: strategy.pruneExcludedDirectories === false,
+        });
+        if (!options.extraHash) {
+            return baseHash;
+        }
+        return crypto
+            .createHash("md5")
+            .update(baseHash)
+            .update(options.extraHash)
+            .digest("hex")
+            .slice(0, 32)
+            .toUpperCase();
+    }
+    /**
+     * Resolve `filePath` to an absolute path using the same base as
+     * `TerraformAsset`: relative paths are anchored to the directory holding
+     * `cdktf.json`, not `process.cwd()`, so a hash taken here matches the one
+     * `TerraformAsset` computes for the same source even when the app is run
+     * from a subdirectory or a test runner. Unlike `TerraformAsset`, there is
+     * no construct scope to read the `cdktfJsonPath` context from, so this uses
+     * the `findFileAboveCwd` fallback directly.
+     * @param filePath - path passed to {@link AssetHash.of}
+     */
+    static resolvePath(filePath) {
+        if (path.isAbsolute(filePath)) {
+            return filePath;
+        }
+        const cdktfJsonPath = (0, fs_1.findFileAboveCwd)("cdktf.json");
+        if (!cdktfJsonPath) {
+            throw (0, errors_1.assetHashOutOfScopeCdktnJson)(filePath);
+        }
+        return path.resolve(path.dirname(cdktfJsonPath), filePath);
+    }
+    constructor() { }
+}
+exports.AssetHash = AssetHash;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXNzZXQtaGFzaC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9hc3NldC1oYXNoLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSwrQkFBK0I7QUFDL0IsbUNBQW1DO0FBQ25DLCtDQUFpQztBQUNqQywyQ0FBNkI7QUFDN0IscUNBQTBEO0FBQzFELHVEQUEyRTtBQUMzRSxxQ0FHa0I7QUErQmxCOzs7Ozs7O0dBT0c7QUFDSCxNQUFhLFNBQVM7O0lBQ3BCOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7T0F3Qkc7SUFDSSxNQUFNLENBQUMsRUFBRSxDQUFDLFFBQWdCLEVBQUUsVUFBNEIsRUFBRTtRQUMvRCxJQUFJLE9BQU8sQ0FBQyxPQUFPLEVBQUUsTUFBTSxJQUFJLE9BQU8sQ0FBQyxjQUFjLEVBQUUsQ0FBQztZQUN0RCxNQUFNLElBQUEsMkNBQWtDLEdBQUUsQ0FBQztRQUM3QyxDQUFDO1FBRUQsTUFBTSxRQUFRLEdBQUcsU0FBUyxDQUFDLFdBQVcsQ0FBQyxRQUFRLENBQUMsQ0FBQztRQUNqRCxNQUFNLFFBQVEsR0FDWixPQUFPLENBQUMsY0FBYztZQUN0QixJQUFJLHVDQUFxQixDQUFDLE9BQU8sQ0FBQyxPQUFPLElBQUksRUFBRSxDQUFDLENBQUM7UUFFbkQsa0VBQWtFO1FBQ2xFLG1FQUFtRTtRQUNuRSxzRUFBc0U7UUFDdEUsTUFBTSxRQUFRLEdBQUcsSUFBQSxhQUFRLEVBQUMsUUFBUSxFQUFFO1lBQ2xDLFNBQVMsRUFBRSxJQUFJO1lBQ2YsYUFBYSxFQUFFLENBQUMsWUFBWSxFQUFFLFdBQVcsRUFBRSxFQUFFLENBQzNDLFFBQVEsQ0FBQyxPQUFPLENBQUMsRUFBRSxZQUFZLEVBQUUsV0FBVyxFQUFFLENBQUM7WUFDakQsOEJBQThCLEVBQzVCLFFBQVEsQ0FBQyx3QkFBd0IsS0FBSyxLQUFLO1NBQzlDLENBQUMsQ0FBQztRQUVILElBQUksQ0FBQyxPQUFPLENBQUMsU0FBUyxFQUFFLENBQUM7WUFDdkIsT0FBTyxRQUFRLENBQUM7UUFDbEIsQ0FBQztRQUVELE9BQU8sTUFBTTthQUNWLFVBQVUsQ0FBQyxLQUFLLENBQUM7YUFDakIsTUFBTSxDQUFDLFFBQVEsQ0FBQzthQUNoQixNQUFNLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FBQzthQUN6QixNQUFNLENBQUMsS0FBSyxDQUFDO2FBQ2IsS0FBSyxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUM7YUFDWixXQUFXLEVBQUUsQ0FBQztJQUNuQixDQUFDO0lBRUQ7Ozs7Ozs7OztPQVNHO0lBQ0ssTUFBTSxDQUFDLFdBQVcsQ0FBQyxRQUFnQjtRQUN6QyxJQUFJLElBQUksQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLEVBQUUsQ0FBQztZQUM5QixPQUFPLFFBQVEsQ0FBQztRQUNsQixDQUFDO1FBQ0QsTUFBTSxhQUFhLEdBQUcsSUFBQSxxQkFBZ0IsRUFBQyxZQUFZLENBQUMsQ0FBQztRQUNyRCxJQUFJLENBQUMsYUFBYSxFQUFFLENBQUM7WUFDbkIsTUFBTSxJQUFBLHFDQUE0QixFQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQy9DLENBQUM7UUFDRCxPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxhQUFhLENBQUMsRUFBRSxRQUFRLENBQUMsQ0FBQztJQUM3RCxDQUFDO0lBRUQsZ0JBQXVCLENBQUM7O0FBakYxQiw4QkFrRkMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgKGMpIEhhc2hpQ29ycCwgSW5jXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogTVBMLTIuMFxuaW1wb3J0ICogYXMgY3J5cHRvIGZyb20gXCJjcnlwdG9cIjtcbmltcG9ydCAqIGFzIHBhdGggZnJvbSBcInBhdGhcIjtcbmltcG9ydCB7IGhhc2hQYXRoLCBmaW5kRmlsZUFib3ZlQ3dkIH0gZnJvbSBcIi4vcHJpdmF0ZS9mc1wiO1xuaW1wb3J0IHsgRXhjbHVkZUlnbm9yZVN0cmF0ZWd5LCBJSWdub3JlU3RyYXRlZ3kgfSBmcm9tIFwiLi9pZ25vcmUtc3RyYXRlZ3lcIjtcbmltcG9ydCB7XG4gIGFzc2V0SGFzaENvbmZsaWN0aW5nRXhjbHVkZU9wdGlvbnMsXG4gIGFzc2V0SGFzaE91dE9mU2NvcGVDZGt0bkpzb24sXG59IGZyb20gXCIuL2Vycm9yc1wiO1xuXG4vKipcbiAqIE9wdGlvbnMgZm9yIHtAbGluayBBc3NldEhhc2gub2Z9LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIEFzc2V0SGFzaE9wdGlvbnMge1xuICAvKipcbiAgICogUGF0aHMgdG8gZXhjbHVkZSwgcmVsYXRpdmUgdG8gdGhlIGhhc2hlZCBwYXRoLiBDYW5ub3QgYmUgY29tYmluZWQgd2l0aFxuICAgKiBgaWdub3JlU3RyYXRlZ3lgLCB3aGljaCByZXBsYWNlcyB0aGlzIG1hdGNoZXIgcmF0aGVyIHRoYW4gbGF5ZXJpbmcgb25cbiAgICogdG9wIG9mIGl0LlxuICAgKlxuICAgKiBAZGVmYXVsdCAtIG5vdGhpbmcgaXMgZXhjbHVkZWRcbiAgICovXG4gIHJlYWRvbmx5IGV4Y2x1ZGU/OiBzdHJpbmdbXTtcblxuICAvKipcbiAgICogRXh0cmEgaW5mb3JtYXRpb24gdG8gZm9sZCBpbnRvIHRoZSBoYXNoLlxuICAgKlxuICAgKiBAZGVmYXVsdCAtIG5vIGV4dHJhIGRhdGFcbiAgICovXG4gIHJlYWRvbmx5IGV4dHJhSGFzaD86IHN0cmluZztcblxuICAvKipcbiAgICogRXhjbHVzaW9uIG1hdGNoaW5nLCBmb3IgY2FsbGVycyB0aGF0IG5lZWQgYC5naXRpZ25vcmVgIC8gYC5kb2NrZXJpZ25vcmVgXG4gICAqIHBhcml0eSByYXRoZXIgdGhhbiB0aGUgYnVpbHQtaW4gZXhhY3QtcGF0aCAvIHN1ZmZpeCAvIGRpcmVjdG9yeSBtYXRjaGVyLlxuICAgKlxuICAgKiBAZGVmYXVsdCAtIGBleGNsdWRlYCBpcyB1c2VkIHdpdGggdGhlIGJ1aWx0LWluIG1hdGNoZXJcbiAgICovXG4gIHJlYWRvbmx5IGlnbm9yZVN0cmF0ZWd5PzogSUlnbm9yZVN0cmF0ZWd5O1xufVxuXG4vKipcbiAqIENvbXB1dGVzIGEgY29udGVudCBoYXNoIG9mIGEgZmlsZSBvciBkaXJlY3Rvcnkgd2l0aG91dCBzdGFnaW5nIGl0LlxuICpcbiAqIFByb3ZpZGVycyB0aGF0IHJlYWQgYSBsb2NhbCBwYXRoIGRpcmVjdGx5IOKAlCBhIERvY2tlciBidWlsZCBgY29udGV4dGAsIGZvclxuICogZXhhbXBsZSDigJQgbmVlZCBhIGNvbnRlbnQgaGFzaCB0byBkcml2ZSBgdHJpZ2dlcnNgLCBidXQgaGF2ZSBubyB1c2UgZm9yIGFcbiAqIHN0YWdlZCBjb3B5IG9mIHRoZSBzb3VyY2UuIGBBc3NldGAgYW5kIGBUZXJyYWZvcm1Bc3NldGAgYWx3YXlzIHByb2R1Y2UgYVxuICogc3RhZ2VkIGNvcHk7IHRoaXMgaXMgdGhlIGlkZW50aXR5IGhhbGYgd2l0aG91dCB0aGUgc3RhZ2luZyBoYWxmLlxuICovXG5leHBvcnQgY2xhc3MgQXNzZXRIYXNoIHtcbiAgLyoqXG4gICAqIENvbnRlbnQgaGFzaCBvZiBhIGZpbGUgb3IgZGlyZWN0b3J5LCB3aXRob3V0IHN0YWdpbmcgaXQuXG4gICAqXG4gICAqIFRoaXMgaXMgYSBoYXNoIG9mIHRoZSBzb3VyY2UgdHJlZSwgYW5kIGl0IGRvZXMgbm90IGRlcGVuZCBvbiBob3cgdGhlXG4gICAqIHNvdXJjZSBpcyBsYXRlciBwYWNrYWdlZC4gYGhhc2hQYXRoYCBpcyBhbHdheXMgY2FsbGVkIHdpdGggYGFyY2hpdmVgXG4gICAqIHVuc2V0LCBzbyBkaXJlY3RvcnkgcmVjb3JkcyBhcmUgcGFydCBvZiB0aGUgZGlnZXN0OyB0aGUgaGFzaCBvZiBhIGdpdmVuXG4gICAqIHRyZWUgaXMgdGhlcmVmb3JlIHRoZSBzYW1lIHdoZXRoZXIgaXQgaXMgbGF0ZXIgY29waWVkLCB6aXBwZWQsIG9yIHBhY2tlZFxuICAgKiBieSBhIGN1c3RvbSBgSUFzc2V0UGFja2FnaW5nYCBzdWNoIGFzIGB0YXIuYnoyYC5cbiAgICpcbiAgICogQSBjb25zZXF1ZW5jZSB3b3J0aCBzdGF0aW5nOiB0aGlzIGRvZXMgbm90IGVxdWFsXG4gICAqIGBUZXJyYWZvcm1Bc3NldChkaXIsIHsgdHlwZTogQVJDSElWRSB9KS5hc3NldEhhc2hgIGZvciBhIGRpcmVjdG9yeSB3aXRoXG4gICAqIHN1YmRpcmVjdG9yaWVzLiBUaGF0IGFzc2V0IGZyYW1lcyBpdHMgaGFzaCB0byB0aGUgZW1pdHRlZCBaSVAsIHdoaWNoIGhhc1xuICAgKiBubyBkaXJlY3RvcnkgZW50cmllcyAoc2VlICMzMjMpLCBzbyBkaXJlY3Rvcnktb25seSBjaGFuZ2VzIG1vdmUgaXQgYW5kXG4gICAqIG5vdCB0aGlzLiBJdCBlcXVhbHMgYSBgRklMRWAgLyBgRElSRUNUT1JZYCBgVGVycmFmb3JtQXNzZXRgIGhhc2ggb25seVxuICAgKiB3aGVuIHRoZSBgY2Fub25pY2FsQXNzZXRIYXNoZXNgIGZsYWcgaXMgZW5hYmxlZCwgc2luY2UgdGhhdCBmbGFnIGlzIHdoYXRcbiAgICogcHV0cyB0aGUgYXNzZXQgb24gdGhpcyBzYW1lIGNhbm9uaWNhbCBzY2hlbWUuXG4gICAqXG4gICAqIEEgcmVsYXRpdmUgYGZpbGVQYXRoYCBpcyByZXNvbHZlZCBhZ2FpbnN0IHRoZSBkaXJlY3RvcnkgY29udGFpbmluZ1xuICAgKiBgY2RrdGYuanNvbmAsIHRoZSBzYW1lIGJhc2UgYFRlcnJhZm9ybUFzc2V0YCB1c2VzLCBzbyBib3RoIGhhc2ggdGhlIHNhbWVcbiAgICogc291cmNlIHJlZ2FyZGxlc3Mgb2YgdGhlIHByb2Nlc3Mgd29ya2luZyBkaXJlY3RvcnkuIEFic29sdXRlIHBhdGhzIGFyZVxuICAgKiB1c2VkIGFzLWlzLiBUaHJvd3MgaWYgYGZpbGVQYXRoYCBpcyByZWxhdGl2ZSBhbmQgbm8gYGNka3RmLmpzb25gIGlzIGZvdW5kXG4gICAqIGFib3ZlIHRoZSB3b3JraW5nIGRpcmVjdG9yeS5cbiAgICogQHBhcmFtIGZpbGVQYXRoIC0gcGF0aCB0byBhIGZpbGUgb3IgZGlyZWN0b3J5IHRvIGhhc2hcbiAgICogQHBhcmFtIG9wdGlvbnMgLSBzZWUge0BsaW5rIEFzc2V0SGFzaE9wdGlvbnN9XG4gICAqL1xuICBwdWJsaWMgc3RhdGljIG9mKGZpbGVQYXRoOiBzdHJpbmcsIG9wdGlvbnM6IEFzc2V0SGFzaE9wdGlvbnMgPSB7fSk6IHN0cmluZyB7XG4gICAgaWYgKG9wdGlvbnMuZXhjbHVkZT8ubGVuZ3RoICYmIG9wdGlvbnMuaWdub3JlU3RyYXRlZ3kpIHtcbiAgICAgIHRocm93IGFzc2V0SGFzaENvbmZsaWN0aW5nRXhjbHVkZU9wdGlvbnMoKTtcbiAgICB9XG5cbiAgICBjb25zdCByZXNvbHZlZCA9IEFzc2V0SGFzaC5yZXNvbHZlUGF0aChmaWxlUGF0aCk7XG4gICAgY29uc3Qgc3RyYXRlZ3kgPVxuICAgICAgb3B0aW9ucy5pZ25vcmVTdHJhdGVneSA/P1xuICAgICAgbmV3IEV4Y2x1ZGVJZ25vcmVTdHJhdGVneShvcHRpb25zLmV4Y2x1ZGUgPz8gW10pO1xuXG4gICAgLy8gUGlubmVkIHRvIHRoZSBjYW5vbmljYWwgc2NoZW1lOiB0aGlzIGlzIGEgYnJhbmQtbmV3IEFQSSB3aXRoIG5vXG4gICAgLy8gZXhpc3RpbmcgaGFzaGVzIHRvIHByZXNlcnZlLCBzbyBpdCBoYXMgbm8gcmVhc29uIHRvIHN0YXJ0IG9uIHRoZVxuICAgIC8vIGxlZ2FjeSBzY2hlbWUgdGhhdCBgY2Fub25pY2FsQXNzZXRIYXNoZXNgIGV4aXN0cyB0byBtb3ZlIGF3YXkgZnJvbS5cbiAgICBjb25zdCBiYXNlSGFzaCA9IGhhc2hQYXRoKHJlc29sdmVkLCB7XG4gICAgICBjYW5vbmljYWw6IHRydWUsXG4gICAgICBzaG91bGRFeGNsdWRlOiAocmVsYXRpdmVQYXRoLCBpc0RpcmVjdG9yeSkgPT5cbiAgICAgICAgc3RyYXRlZ3kuaWdub3Jlcyh7IHJlbGF0aXZlUGF0aCwgaXNEaXJlY3RvcnkgfSksXG4gICAgICBkZXNjZW5kSW50b0V4Y2x1ZGVkRGlyZWN0b3JpZXM6XG4gICAgICAgIHN0cmF0ZWd5LnBydW5lRXhjbHVkZWREaXJlY3RvcmllcyA9PT0gZmFsc2UsXG4gICAgfSk7XG5cbiAgICBpZiAoIW9wdGlvbnMuZXh0cmFIYXNoKSB7XG4gICAgICByZXR1cm4gYmFzZUhhc2g7XG4gICAgfVxuXG4gICAgcmV0dXJuIGNyeXB0b1xuICAgICAgLmNyZWF0ZUhhc2goXCJtZDVcIilcbiAgICAgIC51cGRhdGUoYmFzZUhhc2gpXG4gICAgICAudXBkYXRlKG9wdGlvbnMuZXh0cmFIYXNoKVxuICAgICAgLmRpZ2VzdChcImhleFwiKVxuICAgICAgLnNsaWNlKDAsIDMyKVxuICAgICAgLnRvVXBwZXJDYXNlKCk7XG4gIH1cblxuICAvKipcbiAgICogUmVzb2x2ZSBgZmlsZVBhdGhgIHRvIGFuIGFic29sdXRlIHBhdGggdXNpbmcgdGhlIHNhbWUgYmFzZSBhc1xuICAgKiBgVGVycmFmb3JtQXNzZXRgOiByZWxhdGl2ZSBwYXRocyBhcmUgYW5jaG9yZWQgdG8gdGhlIGRpcmVjdG9yeSBob2xkaW5nXG4gICAqIGBjZGt0Zi5qc29uYCwgbm90IGBwcm9jZXNzLmN3ZCgpYCwgc28gYSBoYXNoIHRha2VuIGhlcmUgbWF0Y2hlcyB0aGUgb25lXG4gICAqIGBUZXJyYWZvcm1Bc3NldGAgY29tcHV0ZXMgZm9yIHRoZSBzYW1lIHNvdXJjZSBldmVuIHdoZW4gdGhlIGFwcCBpcyBydW5cbiAgICogZnJvbSBhIHN1YmRpcmVjdG9yeSBvciBhIHRlc3QgcnVubmVyLiBVbmxpa2UgYFRlcnJhZm9ybUFzc2V0YCwgdGhlcmUgaXNcbiAgICogbm8gY29uc3RydWN0IHNjb3BlIHRvIHJlYWQgdGhlIGBjZGt0Zkpzb25QYXRoYCBjb250ZXh0IGZyb20sIHNvIHRoaXMgdXNlc1xuICAgKiB0aGUgYGZpbmRGaWxlQWJvdmVDd2RgIGZhbGxiYWNrIGRpcmVjdGx5LlxuICAgKiBAcGFyYW0gZmlsZVBhdGggLSBwYXRoIHBhc3NlZCB0byB7QGxpbmsgQXNzZXRIYXNoLm9mfVxuICAgKi9cbiAgcHJpdmF0ZSBzdGF0aWMgcmVzb2x2ZVBhdGgoZmlsZVBhdGg6IHN0cmluZyk6IHN0cmluZyB7XG4gICAgaWYgKHBhdGguaXNBYnNvbHV0ZShmaWxlUGF0aCkpIHtcbiAgICAgIHJldHVybiBmaWxlUGF0aDtcbiAgICB9XG4gICAgY29uc3QgY2RrdGZKc29uUGF0aCA9IGZpbmRGaWxlQWJvdmVDd2QoXCJjZGt0Zi5qc29uXCIpO1xuICAgIGlmICghY2RrdGZKc29uUGF0aCkge1xuICAgICAgdGhyb3cgYXNzZXRIYXNoT3V0T2ZTY29wZUNka3RuSnNvbihmaWxlUGF0aCk7XG4gICAgfVxuICAgIHJldHVybiBwYXRoLnJlc29sdmUocGF0aC5kaXJuYW1lKGNka3RmSnNvblBhdGgpLCBmaWxlUGF0aCk7XG4gIH1cblxuICBwcml2YXRlIGNvbnN0cnVjdG9yKCkge31cbn1cbiJdfQ==

package/lib/asset-staging.d.ts

@@ -0,0 +1,180 @@
+import { Construct } from "constructs";
+import { AssetOptions, IAsset, IAssetBundler, IAssetPackaging } from "./assets";
+import { IIgnoreStrategy } from "./ignore-strategy";
+/**
+ * Context key for a value folded into every computed asset hash in the
+ * construct tree, alongside `extraHash`. A bulk cache-busting escape hatch —
+ * `extraHash` is scoped to one asset, this is scoped to the whole app.
+ */
+export declare const ASSET_HASH_SALT_CONTEXT_KEY = "cdktn:assetHashSalt";
+/**
+ * Options for {@link AssetStaging}.
+ */
+export interface AssetStagingOptions extends AssetOptions {
+    /**
+     * Absolute path to the source file or directory. Resolving a relative path
+     * against `cdktf.json` is the caller's responsibility.
+     */
+    readonly sourcePath: string;
+    /**
+     * 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`.
+     */
+    readonly packaging: IAssetPackaging;
+    /**
+     * 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
+     */
+    readonly exclude?: string[];
+    /**
+     * 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
+     */
+    readonly ignoreStrategy?: IIgnoreStrategy;
+    /**
+     * Extra information to fold into the hash (e.g. build instructions and
+     * other inputs).
+     *
+     * @default - no extra hash
+     */
+    readonly extraHash?: string;
+    /**
+     * 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
+     */
+    readonly bundler?: IAssetBundler;
+    /**
+     * 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
+     */
+    readonly displayName?: string;
+}
+/**
+ * Resolves an asset's identity and stages its content to disk.
+ *
+ * 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.
+ */
+export declare class AssetStaging extends Construct implements IAsset {
+    private readonly sourcePath;
+    private readonly displayName;
+    private readonly ignoreStrategy;
+    private readonly hasExclusions;
+    private readonly hashCache;
+    private readonly bundler?;
+    /**
+     * Output of an eager `OUTPUT`-hash build, carried to `stage()` for reuse.
+     *
+     * Undefined on every other path, where the build is deferred or absent.
+     */
+    private eagerBuild?;
+    /**
+     * Set once `stage()` has run, so a second call cannot rebuild. An eager
+     * `OUTPUT` build is captured at construction and consumed by the first
+     * `stage()`; without this guard a second call would fall through to the
+     * deferred build path and stage bytes that no longer match the hash.
+     */
+    private staged;
+    readonly packaging: IAssetPackaging;
+    readonly isDirectory: boolean;
+    readonly assetHash: string;
+    constructor(scope: Construct, id: string, props: AssetStagingOptions);
+    private resolveAssetHash;
+    /**
+     * Hash the source tree, honoring the ignore strategy.
+     *
+     * Cached per synth so an asset referenced more than once is walked once.
+     */
+    private hashSource;
+    /**
+     * Build the bundler's output eagerly and hash the built artifact.
+     *
+     * The output is stashed for `stage()` to reuse, so the build is not
+     * repeated. It is hashed verbatim: `exclude` filters the source a bundler
+     * reads, not the artifact it produces.
+     */
+    private hashOutput;
+    /**
+     * Run the bundler against the filtered source and return its output.
+     *
+     * The bundler is handed an absolute `source` (its cwd is its own, so a
+     * relative path would resolve elsewhere) that has already had `exclude`
+     * applied. Materialising the filtered input here is what makes the bundler
+     * read exactly the tree the hash was taken over, which a raw source
+     * hand-off would not, since `hashSource` honours `exclude`.
+     */
+    private runBundle;
+    /**
+     * Reject a bundler result whose declared shape does not match what is on
+     * disk, or does not match the packaging.
+     *
+     * Catching the mismatch here turns an opaque EISDIR/EPERM at pack time into
+     * a clear error naming the packaging the bundler's output shape needs.
+     */
+    private validateOutputShape;
+    /**
+     * Whether the packaging stages a single file verbatim (AssetType.FILE).
+     *
+     * A verbatim-file packaging neither produces a directory nor reads one as
+     * its source. Derived from existing `IAssetPackaging` flags so out-of-tree
+     * packagings need no new interface member.
+     */
+    private get stagesSingleFile();
+    /**
+     * Absolute path to the source the bundler should read.
+     *
+     * With no exclusions, or with a file source, the resolved source is handed
+     * over directly — a file has no children to filter, matching `hashSource`,
+     * which only ever applies the ignore strategy to a directory's entries and
+     * never to the root itself. Otherwise the excluded source tree is
+     * materialised into the scratch directory, so the bundler sees the same
+     * file set the hash was taken over.
+     */
+    private filteredSource;
+    /**
+     * Stage the asset's content to `targetPath`.
+     *
+     * 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`.
+     */
+    stage(targetPath: string): void;
+    /**
+     * Remove a bundler scratch directory and drop it from the exit-sweep set.
+     */
+    private cleanupScratch;
+    /**
+     * Package a bundler's output into `targetPath`, verbatim.
+     *
+     * The output's shape was already validated against the packaging in
+     * {@link runBundle}, so the packaging handles the source directly — a file
+     * source for AssetType.FILE, a directory source otherwise.
+     *
+     * The ignore strategy is deliberately not applied. `exclude` filters the
+     * source a bundler reads, not its product: an install-style bundler
+     * (`npm install --production`, `pip install -t`) writes exactly the
+     * dependency directory a user excludes from source, and re-applying the
+     * exclusion would ship an artifact missing those dependencies.
+     */
+    private packBundlerOutput;
+}