@composurecdk/cloudformation 0.6.0 → 0.8.0

package/dist/commonjs/apply-builder-tags.d.ts

@@ -0,0 +1,32 @@
+import { type IConstruct } from "constructs";
+/**
+ * Applies every accumulated tag to every {@link IConstruct} reachable in a
+ * builder result.
+ *
+ * Recursively descends through plain-object literals, tagging every
+ * `IConstruct` it finds. Stops at:
+ *
+ * - **Constructs** — tagged via `Tags.of(...).add(...)`. The CDK Aspect
+ *   schedules tag application across the construct's subtree at
+ *   synth-prepare time, so the walker does not recurse into the construct's
+ *   internals.
+ * - **Class instances that aren't constructs** (e.g. `PolicyDocument`) —
+ *   skipped. Plain-object detection requires `Object.prototype` as the
+ *   prototype, so class instances are opaque to the walker.
+ * - **Arrays and primitives** — skipped.
+ *
+ * The contract this implements: every construct exposed in a builder's
+ * result type is a tag target. Wrapper shapes such as
+ * `Record<string, { construct: ..., metadata: ... }>` are unwrapped
+ * naturally — the walker descends through the plain-object value and tags
+ * the construct field. Authors do not need an opt-in marker; if a construct
+ * appears in the result, it is tagged.
+ */
+export declare function applyBuilderTags(result: object, tags: ReadonlyMap<string, string>): void;
+/**
+ * Applies every entry of `tags` to `target` via `Tags.of(target).add(...)`.
+ * Accepts any iterable of `[key, value]` pairs so callers can pass `Map`,
+ * `Object.entries(record)`, or other compatible sources without copying.
+ */
+export declare function applyTagsToConstruct(target: IConstruct, tags: Iterable<[string, string]>): void;
+//# sourceMappingURL=apply-builder-tags.d.ts.map

package/dist/commonjs/apply-builder-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-builder-tags.d.ts","sourceRoot":"","sources":["../../src/apply-builder-tags.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAMxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGxF;AAcD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAK/F"}

package/dist/commonjs/apply-builder-tags.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyBuilderTags = applyBuilderTags;
+exports.applyTagsToConstruct = applyTagsToConstruct;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const constructs_1 = require("constructs");
+function isConstruct(value) {
+    return value !== null && typeof value === "object" && constructs_1.Construct.isConstruct(value);
+}
+/**
+ * Applies every accumulated tag to every {@link IConstruct} reachable in a
+ * builder result.
+ *
+ * Recursively descends through plain-object literals, tagging every
+ * `IConstruct` it finds. Stops at:
+ *
+ * - **Constructs** — tagged via `Tags.of(...).add(...)`. The CDK Aspect
+ *   schedules tag application across the construct's subtree at
+ *   synth-prepare time, so the walker does not recurse into the construct's
+ *   internals.
+ * - **Class instances that aren't constructs** (e.g. `PolicyDocument`) —
+ *   skipped. Plain-object detection requires `Object.prototype` as the
+ *   prototype, so class instances are opaque to the walker.
+ * - **Arrays and primitives** — skipped.
+ *
+ * The contract this implements: every construct exposed in a builder's
+ * result type is a tag target. Wrapper shapes such as
+ * `Record<string, { construct: ..., metadata: ... }>` are unwrapped
+ * naturally — the walker descends through the plain-object value and tags
+ * the construct field. Authors do not need an opt-in marker; if a construct
+ * appears in the result, it is tagged.
+ */
+function applyBuilderTags(result, tags) {
+    if (tags.size === 0)
+        return;
+    walkAndTag(result, tags);
+}
+function walkAndTag(value, tags) {
+    if (isConstruct(value)) {
+        applyTagsToConstruct(value, tags);
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const inner of Object.values(value)) {
+            walkAndTag(inner, tags);
+        }
+    }
+}
+/**
+ * Applies every entry of `tags` to `target` via `Tags.of(target).add(...)`.
+ * Accepts any iterable of `[key, value]` pairs so callers can pass `Map`,
+ * `Object.entries(record)`, or other compatible sources without copying.
+ */
+function applyTagsToConstruct(target, tags) {
+    const t = aws_cdk_lib_1.Tags.of(target);
+    for (const [key, value] of tags) {
+        t.add(key, value);
+    }
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    // Accept both `{...}` literals and `Object.create(null)` dictionaries — the
+    // latter is a common idiom for prototype-pollution-safe key/value maps and
+    // would otherwise be silently skipped here.
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+//# sourceMappingURL=apply-builder-tags.js.map

package/dist/commonjs/apply-builder-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-builder-tags.js","sourceRoot":"","sources":["../../src/apply-builder-tags.ts"],"names":[],"mappings":";;AA8BA,4CAGC;AAmBD,oDAKC;AAzDD,6CAAmC;AACnC,2CAAwD;AAExD,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,sBAAS,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,gBAAgB,CAAC,MAAc,EAAE,IAAiC;IAChF,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IAC5B,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,IAAiC;IACnE,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,OAAO;IACT,CAAC;IACD,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAAC,MAAkB,EAAE,IAAgC;IACvF,MAAM,CAAC,GAAG,kBAAI,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAChC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,4EAA4E;IAC5E,2EAA2E;IAC3E,4CAA4C;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAkB,CAAC;IAC5D,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,CAAC;AACtD,CAAC"}

package/dist/commonjs/index.d.ts

@@ -0,0 +1,8 @@
+export { createStackBuilder, type IStackBuilder, type StackBuilderResult, } from "./stack-builder.js";
+export { singleStack, groupedStacks } from "./strategies.js";
+export { outputs, type OutputDefinition, type OutputDefinitions } from "./outputs.js";
+export { taggedBuilder, type ITaggedBuilder, TAG_OVERRIDE_WARNING_NAME } from "./tagged-builder.js";
+export { applyBuilderTags } from "./apply-builder-tags.js";
+export { validateTag } from "./tag-validator.js";
+export { tags, type TagDefinitions } from "./tags.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/commonjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tags = exports.validateTag = exports.applyBuilderTags = exports.TAG_OVERRIDE_WARNING_NAME = exports.taggedBuilder = exports.outputs = exports.groupedStacks = exports.singleStack = exports.createStackBuilder = void 0;
+var stack_builder_js_1 = require("./stack-builder.js");
+Object.defineProperty(exports, "createStackBuilder", { enumerable: true, get: function () { return stack_builder_js_1.createStackBuilder; } });
+var strategies_js_1 = require("./strategies.js");
+Object.defineProperty(exports, "singleStack", { enumerable: true, get: function () { return strategies_js_1.singleStack; } });
+Object.defineProperty(exports, "groupedStacks", { enumerable: true, get: function () { return strategies_js_1.groupedStacks; } });
+var outputs_js_1 = require("./outputs.js");
+Object.defineProperty(exports, "outputs", { enumerable: true, get: function () { return outputs_js_1.outputs; } });
+var tagged_builder_js_1 = require("./tagged-builder.js");
+Object.defineProperty(exports, "taggedBuilder", { enumerable: true, get: function () { return tagged_builder_js_1.taggedBuilder; } });
+Object.defineProperty(exports, "TAG_OVERRIDE_WARNING_NAME", { enumerable: true, get: function () { return tagged_builder_js_1.TAG_OVERRIDE_WARNING_NAME; } });
+var apply_builder_tags_js_1 = require("./apply-builder-tags.js");
+Object.defineProperty(exports, "applyBuilderTags", { enumerable: true, get: function () { return apply_builder_tags_js_1.applyBuilderTags; } });
+var tag_validator_js_1 = require("./tag-validator.js");
+Object.defineProperty(exports, "validateTag", { enumerable: true, get: function () { return tag_validator_js_1.validateTag; } });
+var tags_js_1 = require("./tags.js");
+Object.defineProperty(exports, "tags", { enumerable: true, get: function () { return tags_js_1.tags; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,uDAI4B;AAH1B,sHAAA,kBAAkB,OAAA;AAIpB,iDAA6D;AAApD,4GAAA,WAAW,OAAA;AAAE,8GAAA,aAAa,OAAA;AACnC,2CAAsF;AAA7E,qGAAA,OAAO,OAAA;AAChB,yDAAoG;AAA3F,kHAAA,aAAa,OAAA;AAAuB,8HAAA,yBAAyB,OAAA;AACtE,iEAA2D;AAAlD,yHAAA,gBAAgB,OAAA;AACzB,uDAAiD;AAAxC,+GAAA,WAAW,OAAA;AACpB,qCAAsD;AAA7C,+FAAA,IAAI,OAAA"}

package/dist/commonjs/outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.d.ts","sourceRoot":"","sources":["../../src/outputs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAW,MAAM,oBAAoB,CAAC;AAEnF;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACzD,uDAAuD;IACvD,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE1B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CA0BhG"}

package/dist/commonjs/outputs.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outputs = outputs;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const core_1 = require("@composurecdk/core");
+/**
+ * Returns an {@link AfterBuildHook} that creates CloudFormation stack outputs
+ * from the composed system's build results.
+ *
+ * Each output definition's `value` can be a concrete string or a {@link Ref}
+ * that is resolved against the build results. An optional `scope` routes
+ * individual outputs to specific stacks — either as a direct `IConstruct`
+ * or as a component key string (statically typed against the composed
+ * system's component keys).
+ *
+ * Intended for use with {@link ComposedSystem.afterBuild}.
+ *
+ * @param defs - A record of output definitions keyed by logical name.
+ * @returns An {@link AfterBuildHook} that creates `CfnOutput` constructs.
+ *
+ * @example
+ * ```ts
+ * import { compose, ref } from "@composurecdk/core";
+ * import { outputs } from "@composurecdk/cloudformation";
+ *
+ * compose(
+ *   { site: createBucketBuilder(), cdn: createDistributionBuilder(), dns: createZoneBuilder() },
+ *   { site: [], cdn: ["site"], dns: [] },
+ * )
+ *   .withStacks({ site: siteStack, cdn: siteStack, dns: dnsStack })
+ *   .afterBuild(outputs({
+ *     DistributionUrl: {
+ *       value: ref("cdn", (r: DistributionBuilderResult) =>
+ *         `https://${r.distribution.distributionDomainName}`),
+ *       scope: "cdn",
+ *     },
+ *     BucketName: {
+ *       value: ref("site", (r: BucketBuilderResult) => r.bucket.bucketName),
+ *       scope: siteStack,
+ *     },
+ *     NameServers: {
+ *       value: ref("dns", (r: ZoneBuilderResult) =>
+ *         Fn.join(",", r.zone.hostedZoneNameServers!)),
+ *       scope: "dns",
+ *     },
+ *   }))
+ *   .build(app, "StaticWebsite");
+ * ```
+ */
+function outputs(defs) {
+    return (scope, _id, results, componentScopes) => {
+        const resultAsContext = results;
+        const scopesByKey = componentScopes;
+        for (const [name, def] of Object.entries(defs)) {
+            let target;
+            if (typeof def.scope === "string") {
+                const resolved = scopesByKey[def.scope];
+                if (resolved === undefined) {
+                    throw new Error(`outputs(): "${name}" refers to unknown component "${def.scope}".`);
+                }
+                target = resolved;
+            }
+            else if (def.scope !== undefined) {
+                target = def.scope;
+            }
+            else {
+                target = scope;
+            }
+            new aws_cdk_lib_1.CfnOutput(target, name, {
+                value: (0, core_1.resolve)(def.value, resultAsContext),
+                ...(def.description !== undefined ? { description: def.description } : {}),
+                ...(def.exportName !== undefined ? { exportName: def.exportName } : {}),
+            });
+        }
+    };
+}
+//# sourceMappingURL=outputs.js.map

package/dist/commonjs/outputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.js","sourceRoot":"","sources":["../../src/outputs.ts"],"names":[],"mappings":";;AAyFA,0BA0BC;AAnHD,6CAAwC;AAExC,6CAAmF;AA2CnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,SAAgB,OAAO,CAA4B,IAA0B;IAC3E,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE;QAC9C,MAAM,eAAe,GAAG,OAAiC,CAAC;QAC1D,MAAM,WAAW,GAAG,eAAyD,CAAC;QAE9E,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,IAAI,MAAkB,CAAC;YACvB,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACxC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,kCAAkC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;gBACtF,CAAC;gBACD,MAAM,GAAG,QAAQ,CAAC;YACpB,CAAC;iBAAM,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACnC,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,KAAK,CAAC;YACjB,CAAC;YAED,IAAI,uBAAS,CAAC,MAAM,EAAE,IAAI,EAAE;gBAC1B,KAAK,EAAE,IAAA,cAAO,EAAC,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC;gBAC1C,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1E,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/{stack-builder.d.ts → commonjs/stack-builder.d.ts}

@@ -1,6 +1,7 @@
 import { Stack, type StackProps } from "aws-cdk-lib";
 import { type IConstruct } from "constructs";
-import { COPY_STATE, type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { type Lifecycle } from "@composurecdk/core";
+import { type ITaggedBuilder } from "./tagged-builder.js";
 /**
  * The build output of a {@link IStackBuilder}. Contains the CDK Stack
  * created during {@link Lifecycle.build}.
@@ -22,30 +23,23 @@ export interface StackBuilderResult {
  * builder to a strategy that may be invoked after further configuration of
  * the original, pass `builder.copy()` to snapshot the current state.
  *
+ * Tags accumulated via {@link ITaggedBuilder.tag | .tag()} or
+ * {@link ITaggedBuilder.tags | .tags()} are applied to the resulting Stack.
+ * CloudFormation propagates stack-level tags to every resource the stack
+ * contains, so a single `.tag()` call on a stack reaches everything inside.
+ *
  * @example
  * ```ts
  * const { stack } = createStackBuilder()
  *   .description("Network infrastructure")
  *   .terminationProtection(true)
+ *   .tag("Owner", "platform")
  *   .build(app, "NetworkStack");
  * ```
  */
-export type IStackBuilder = IBuilder<StackProps, StackBuilder> & {
-    /**
-     * Adds a tag to the Stack. Tags are applied to the Stack and propagate
-     * to all resources within it.
-     *
-     * @param key - The tag key.
-     * @param value - The tag value.
-     * @returns The builder for chaining.
-     */
-    tag(key: string, value: string): IStackBuilder;
-};
+export type IStackBuilder = ITaggedBuilder<StackProps, StackBuilder>;
 declare class StackBuilder implements Lifecycle<StackBuilderResult> {
-    #private;
     props: Partial<StackProps>;
-    tag(key: string, value: string): this;
-    [COPY_STATE](next: StackBuilder): void;
     build(scope: IConstruct, id: string): StackBuilderResult;
 }
 /**
@@ -53,9 +47,10 @@ declare class StackBuilder implements Lifecycle<StackBuilderResult> {
  *
  * This is the entry point for declarative stack configuration. The returned
  * builder exposes every {@link StackProps} property as a fluent setter/getter,
- * plus {@link IStackBuilder.tag | .tag()} for adding tags. It implements
- * {@link Lifecycle}, so it composes naturally and can be passed to
- * {@link singleStack} or {@link groupedStacks}.
+ * `.tag(key, value)` / `.tags({...})` for stack-level tagging, and `.copy()`
+ * for variant authoring. It implements {@link Lifecycle}, so it composes
+ * naturally and can be passed to {@link singleStack} or
+ * {@link groupedStacks}.
  *
  * @returns A fluent builder for a CloudFormation Stack.
  *
@@ -65,6 +60,7 @@ declare class StackBuilder implements Lifecycle<StackBuilderResult> {
  * const { stack } = createStackBuilder()
  *   .description("Service layer")
  *   .terminationProtection(true)
+ *   .tag("Owner", "platform")
  *   .build(app, "ServiceStack");
  *
  * // Hand a configured builder to a strategy. Use `.copy()` to snapshot

package/dist/commonjs/stack-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-builder.d.ts","sourceRoot":"","sources":["../../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;AAErE,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAM;IAEhC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}

package/dist/commonjs/stack-builder.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStackBuilder = createStackBuilder;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const tagged_builder_js_1 = require("./tagged-builder.js");
+class StackBuilder {
+    props = {};
+    build(scope, id) {
+        return { stack: new aws_cdk_lib_1.Stack(scope, id, this.props) };
+    }
+}
+/**
+ * Creates a new {@link IStackBuilder} for configuring a CloudFormation Stack.
+ *
+ * This is the entry point for declarative stack configuration. The returned
+ * builder exposes every {@link StackProps} property as a fluent setter/getter,
+ * `.tag(key, value)` / `.tags({...})` for stack-level tagging, and `.copy()`
+ * for variant authoring. It implements {@link Lifecycle}, so it composes
+ * naturally and can be passed to {@link singleStack} or
+ * {@link groupedStacks}.
+ *
+ * @returns A fluent builder for a CloudFormation Stack.
+ *
+ * @example
+ * ```ts
+ * // Build a stack directly
+ * const { stack } = createStackBuilder()
+ *   .description("Service layer")
+ *   .terminationProtection(true)
+ *   .tag("Owner", "platform")
+ *   .build(app, "ServiceStack");
+ *
+ * // Hand a configured builder to a strategy. Use `.copy()` to snapshot
+ * // when the original may be mutated further.
+ * const base = createStackBuilder()
+ *   .terminationProtection(true)
+ *   .tag("team", "platform");
+ *
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(singleStack(base.copy()))
+ *   .build(app, "MySystem");
+ * ```
+ */
+function createStackBuilder() {
+    return (0, tagged_builder_js_1.taggedBuilder)(StackBuilder);
+}
+//# sourceMappingURL=stack-builder.js.map

package/dist/commonjs/stack-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-builder.js","sourceRoot":"","sources":["../../src/stack-builder.ts"],"names":[],"mappings":";;AAmFA,gDAEC;AArFD,6CAAqD;AAGrD,2DAAyE;AAwCzE,MAAM,YAAY;IAChB,KAAK,GAAwB,EAAE,CAAC;IAEhC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,OAAO,EAAE,KAAK,EAAE,IAAI,mBAAK,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;IACrD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,kBAAkB;IAChC,OAAO,IAAA,iCAAa,EAA2B,YAAY,CAAC,CAAC;AAC/D,CAAC"}

package/dist/commonjs/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAGlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,EAC1C,OAAO,CAAC,EAAE,SAAS,CAAC,kBAAkB,CAAC,GACtC,aAAa,CAGf"}

package/dist/commonjs/strategies.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.singleStack = singleStack;
+exports.groupedStacks = groupedStacks;
+const core_1 = require("@composurecdk/core");
+const stack_builder_js_1 = require("./stack-builder.js");
+/**
+ * Creates a strategy that places all components in a single Stack.
+ *
+ * The Stack is created lazily on the first call to `resolve` and reused
+ * for all subsequent components. The supplied `builder` is invoked at that
+ * point as `builder.build(scope, id).stack`, so any tags applied via the
+ * builder's `.tag()` method land on the resulting Stack.
+ *
+ * The builder's `build()` is called lazily. If the original may be mutated
+ * after this call, pass `builder.copy()` to snapshot the configuration.
+ *
+ * @param builder - Optional builder for configuring the Stack. Defaults to
+ *   a fresh {@link createStackBuilder} per call, producing a plain Stack
+ *   with no extra configuration. For non-Stack scope types, use
+ *   `singleStack` from `@composurecdk/core` directly with a `ScopeFactory`.
+ * @returns A {@link StackStrategy} that groups all components into one Stack.
+ *
+ * @example
+ * ```ts
+ * compose({ handler, api }, { handler: [], api: ["handler"] })
+ *   .withStackStrategy(singleStack())
+ *   .build(app, "MySystem");
+ *
+ * // With a configured builder:
+ * const base = createStackBuilder().tag("team", "platform");
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(singleStack(base.copy()))
+ *   .build(app, "MySystem");
+ * ```
+ */
+function singleStack(builder) {
+    const stackBuilder = builder ?? (0, stack_builder_js_1.createStackBuilder)();
+    return (0, core_1.singleStack)((scope, id) => stackBuilder.build(scope, id).stack);
+}
+/**
+ * Creates a strategy that groups components into named Stacks determined by
+ * a classifier function.
+ *
+ * Components that return the same group key share a Stack. Stacks are
+ * created lazily as new group keys are encountered. The supplied `builder`
+ * is invoked once per group as `builder.build(scope, id).stack` with
+ * `id = ${systemId}-${group}`, so any configured tags propagate to every
+ * Stack the strategy creates.
+ *
+ * The builder's `build()` is called lazily. If the original may be mutated
+ * after this call, pass `builder.copy()` to snapshot the configuration.
+ *
+ * @param classify - A function that maps a component key to a group name.
+ * @param builder - Optional builder for configuring each Stack. Defaults to
+ *   a fresh {@link createStackBuilder} per call. For non-Stack scope types,
+ *   use `groupedStacks` from `@composurecdk/core` directly with a
+ *   `ScopeFactory`.
+ * @returns A {@link StackStrategy} that groups components by classifier output.
+ *
+ * @example
+ * ```ts
+ * compose({ handler, api, table }, { ... })
+ *   .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
+ *   .build(app, "MySystem");
+ *
+ * // With a configured builder, snapshotted via .copy():
+ * const base = createStackBuilder().tag("team", "platform");
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(
+ *     groupedStacks(key => key === "table" ? "persistence" : "service", base.copy()),
+ *   )
+ *   .build(app, "MySystem");
+ * ```
+ */
+function groupedStacks(classify, builder) {
+    const stackBuilder = builder ?? (0, stack_builder_js_1.createStackBuilder)();
+    return (0, core_1.groupedStacks)(classify, (scope, id) => stackBuilder.build(scope, id).stack);
+}
+//# sourceMappingURL=strategies.js.map

package/dist/commonjs/strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../src/strategies.ts"],"names":[],"mappings":";;AAsCA,kCAGC;AAqCD,sCAMC;AApFD,6CAK4B;AAC5B,yDAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,WAAW,CAAC,OAAuC;IACjE,MAAM,YAAY,GAAG,OAAO,IAAI,IAAA,qCAAkB,GAAE,CAAC;IACrD,OAAO,IAAA,kBAAe,EAAC,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,SAAgB,aAAa,CAC3B,QAA0C,EAC1C,OAAuC;IAEvC,MAAM,YAAY,GAAG,OAAO,IAAI,IAAA,qCAAkB,GAAE,CAAC;IACrD,OAAO,IAAA,oBAAiB,EAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC"}

package/dist/commonjs/tag-validator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validates a single tag key/value pair against AWS tag constraints.
+ *
+ * Throws synchronously at the call site so authors see the failure where the
+ * bad value was written, not at deploy time. Validates:
+ *
+ * - `key` is non-empty and at most {@link KEY_MAX} characters.
+ * - `key` does not start with the reserved `aws:` prefix (case-insensitive).
+ * - `value` is at most {@link VALUE_MAX} characters.
+ * - both `key` and `value` use only the AWS-permitted character set.
+ *
+ * The regex matches Unicode letters, digits, and whitespace plus the
+ * documented punctuation set, so non-ASCII tags are accepted as AWS
+ * supports them.
+ */
+export declare function validateTag(key: string, value: string): void;
+/**
+ * Validates every entry of a record via {@link validateTag}, throwing on the
+ * first invalid pair so the failure surfaces at the configuring call site.
+ */
+export declare function validateTagRecord(values: Record<string, string>): void;
+//# sourceMappingURL=tag-validator.d.ts.map

package/dist/commonjs/tag-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-validator.d.ts","sourceRoot":"","sources":["../../src/tag-validator.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2B5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAItE"}

package/dist/commonjs/tag-validator.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTag = validateTag;
+exports.validateTagRecord = validateTagRecord;
+/**
+ * AWS allows letters, digits, whitespace, and the symbols `_ . : / = + - @`
+ * in tag keys and values, with non-ASCII letters/digits permitted via
+ * Unicode classes. Empty values are permitted by AWS for `Value`, but
+ * empty `Key` is not. The character set is validated against this regex.
+ *
+ * `\p{Z}` matches the full Unicode separator class — slightly more
+ * permissive than AWS's documented "white space," but errors on the side
+ * of accepting input that the AWS API may yet reject at deploy time. The
+ * extra rejections happen later but are reported in the API response.
+ *
+ * @see https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html
+ */
+const TAG_CHAR_RE = /^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$/u;
+const KEY_MAX = 128;
+const VALUE_MAX = 256;
+/**
+ * Validates a single tag key/value pair against AWS tag constraints.
+ *
+ * Throws synchronously at the call site so authors see the failure where the
+ * bad value was written, not at deploy time. Validates:
+ *
+ * - `key` is non-empty and at most {@link KEY_MAX} characters.
+ * - `key` does not start with the reserved `aws:` prefix (case-insensitive).
+ * - `value` is at most {@link VALUE_MAX} characters.
+ * - both `key` and `value` use only the AWS-permitted character set.
+ *
+ * The regex matches Unicode letters, digits, and whitespace plus the
+ * documented punctuation set, so non-ASCII tags are accepted as AWS
+ * supports them.
+ */
+function validateTag(key, value) {
+    if (key.length === 0) {
+        throw new Error("Tag key must be non-empty.");
+    }
+    if (key.length > KEY_MAX) {
+        throw new Error(`Tag key "${key}" exceeds ${String(KEY_MAX)}-character limit.`);
+    }
+    if (key.toLowerCase().startsWith("aws:")) {
+        throw new Error(`Tag key "${key}" uses reserved "aws:" prefix; AWS rejects user tags with this prefix.`);
+    }
+    if (!TAG_CHAR_RE.test(key)) {
+        throw new Error(`Tag key "${key}" contains characters outside the AWS tag character set ` +
+            "(letters, digits, whitespace, and `_ . : / = + - @`).");
+    }
+    if (value.length > VALUE_MAX) {
+        throw new Error(`Tag value for key "${key}" exceeds ${String(VALUE_MAX)}-character limit.`);
+    }
+    if (!TAG_CHAR_RE.test(value)) {
+        throw new Error(`Tag value for key "${key}" contains characters outside the AWS tag character set ` +
+            "(letters, digits, whitespace, and `_ . : / = + - @`).");
+    }
+}
+/**
+ * Validates every entry of a record via {@link validateTag}, throwing on the
+ * first invalid pair so the failure surfaces at the configuring call site.
+ */
+function validateTagRecord(values) {
+    for (const [key, value] of Object.entries(values)) {
+        validateTag(key, value);
+    }
+}
+//# sourceMappingURL=tag-validator.js.map

package/dist/commonjs/tag-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-validator.js","sourceRoot":"","sources":["../../src/tag-validator.ts"],"names":[],"mappings":";;AAiCA,kCA2BC;AAMD,8CAIC;AAtED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,GAAG,gCAAgC,CAAC;AAErD,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB;;;;;;;;;;;;;;GAcG;AACH,SAAgB,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,YAAY,GAAG,aAAa,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,YAAY,GAAG,wEAAwE,CACxF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,YAAY,GAAG,0DAA0D;YACvE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,aAAa,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,0DAA0D;YACjF,uDAAuD,CAC1D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,MAA8B;IAC9D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}