@intentius/chant-lexicon-aws 0.46.0 → 0.50.0

package/src/codegen/generate-lexicon.ts

@@ -26,6 +26,11 @@ export interface LexiconEntry {
   writeOnly?: string[];
   primaryIdentifier?: string[];
   deprecatedProperties?: string[];
+  /**
+   * Subset of `deprecatedProperties` that only a regex over the property
+   * description supports; the rest is declared by the Registry schema (#1701).
+   */
+  inferredDeprecations?: string[];
   conditionalCreateOnly?: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
   tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
@@ -72,6 +77,7 @@ export function generateLexiconJSON(
         ...(r.resource.writeOnly.length > 0 && { writeOnly: r.resource.writeOnly }),
         ...(r.resource.primaryIdentifier.length > 0 && { primaryIdentifier: r.resource.primaryIdentifier }),
         ...(r.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+        ...(r.resource.inferredDeprecations?.length && { inferredDeprecations: r.resource.inferredDeprecations }),
         ...(r.resource.conditionalCreateOnly?.length && { conditionalCreateOnly: r.resource.conditionalCreateOnly }),
         ...(r.resource.replacementStrategy && { replacementStrategy: r.resource.replacementStrategy }),
         ...(r.resource.tagging && { tagging: r.resource.tagging }),

package/src/codegen/sam.ts

@@ -59,6 +59,7 @@ function samFunction(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -147,6 +148,7 @@ function samApi(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -200,6 +202,7 @@ function samHttpApi(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -236,6 +239,7 @@ function samSimpleTable(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -273,6 +277,7 @@ function samLayerVersion(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],
@@ -306,6 +311,7 @@ function samStateMachine(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [
@@ -339,6 +345,7 @@ function samApplication(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],
@@ -360,6 +367,7 @@ function samConnector(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],
@@ -397,6 +405,7 @@ function samGraphQLApi(): SchemaParseResult {
       writeOnly: [],
       primaryIdentifier: [],
       deprecatedProperties: [],
+      inferredDeprecations: [],
       conditionalCreateOnly: [],
     },
     propertyTypes: [],

package/src/components/host-delivery.ts

@@ -73,9 +73,10 @@ function resolveTargets(
  * Deploy a revision to a host (fleet) via AWS CodeDeploy: create the
  * deployment, then wait for a terminal status. Rollback re-invokes
  * `stopAndRollback` against the deployment id this step created (captured in
- * a closure-scoped map keyed by application/deploymentGroup, since the
- * driver's saga rollback calls `rollback(ctx, sameInput)` rather than passing
- * `run`'s output) — riding CodeDeploy's own native automatic rollback to the
+ * a closure-scoped map keyed by application/deploymentGroup; the driver now
+ * also passes `run`'s output as `rollback`'s optional third arg (#1944), but
+ * this capability's input-derived key needs neither channel to resolve
+ * identity) — riding CodeDeploy's own native automatic rollback to the
  * last known-good revision rather than a chant-scripted compensation, the
  * "auto" rollback style the Neo4j pilot's docs comment contrasts with the
  * ALB/ECS pilot's component-declared one.

package/src/composites/agentcore-agent.ts

@@ -45,19 +45,36 @@ export function agentCoreDefaultEndpointArn(runtime: InstanceType<typeof Runtime
 }
 
 /**
- * AgentCore's `Runtime`/`RuntimeEndpoint`/`Memory` `Name`/`AgentRuntimeName`
- * fields are all bound to the CFN registry pattern
- * `^[a-zA-Z][a-zA-Z0-9_]{0,47}$` (spot-checked against the CloudFormation
- * schema for #882 — no hyphens, unlike chant's usual kebab-case component
- * names). `Gateway`/`GatewayTarget`/`WorkloadIdentity` names accept hyphens,
- * so only the Runtime family needs sanitizing. Non-identifier characters
- * become `_`, and a leading digit/underscore gets an `A` prefix so the result
- * always starts with a letter.
+ * Bedrock AgentCore's real limits, verified against the CloudFormation
+ * registry schema for `AWS::BedrockAgentCore::{Runtime,RuntimeEndpoint,Memory}`
+ * (#882).
+ *
+ * Exported for the same reason as `MICROVM_LIMITS` (#1374, #1420): a
+ * consumer driving AgentCore through another control plane needs the same
+ * numbers, and copying them is how two sources of truth start.
+ */
+export const AGENTCORE_LIMITS = {
+  /**
+   * `Runtime`/`RuntimeEndpoint`/`Memory` `Name`/`AgentRuntimeName` fields
+   * are bound to this pattern — no hyphens, unlike chant's usual kebab-case
+   * component names. `Gateway`/`GatewayTarget`/`WorkloadIdentity` names
+   * accept hyphens, so only the Runtime family needs sanitizing.
+   */
+  runtimeNamePattern: /^[a-zA-Z][a-zA-Z0-9_]{0,47}$/,
+  maxRuntimeNameLength: 48,
+  /** `Memory` event retention bounds, in days. */
+  memoryEventExpiryDays: { min: 3, max: 365, default: 30 },
+} as const;
+
+/**
+ * Non-identifier characters become `_`, and a leading digit/underscore gets
+ * an `A` prefix so the result always starts with a letter — then truncated
+ * to {@link AGENTCORE_LIMITS}'s `maxRuntimeNameLength`.
  */
 function toRuntimeIdentifier(name: string): string {
   const cleaned = name.replace(/[^a-zA-Z0-9_]/g, "_");
   const identifier = /^[a-zA-Z]/.test(cleaned) ? cleaned : `A${cleaned}`;
-  return identifier.slice(0, 48);
+  return identifier.slice(0, AGENTCORE_LIMITS.maxRuntimeNameLength);
 }
 
 /**
@@ -117,7 +134,7 @@ export interface AgentCoreAgentProps {
    * managed one and fails on a real apply (#978, see the composite doc).
    */
   endpointName?: string;
-  /** Memory event retention, in days. CFN bounds: 3-365. Default: 30. */
+  /** Memory event retention, in days. Bounds: {@link AGENTCORE_LIMITS.memoryEventExpiryDays}. */
   memoryEventExpiryDays?: number;
   /** Gateway authorizer. Mirrors the generated `BedrockAgentCoreGateway_AuthorizerType` CFN enum. Default: "AWS_IAM". */
   gatewayAuthorizerType?: "CUSTOM_JWT" | "AWS_IAM" | "NONE" | "AUTHENTICATE_ONLY";
@@ -194,9 +211,14 @@ export const AgentCoreAgent = Composite<AgentCoreAgentProps, AgentCoreAgentResul
   if (networkMode === "VPC" && (props.vpcSubnetIds === undefined || props.vpcSecurityGroupIds === undefined)) {
     throw new Error("AgentCoreAgent requires vpcSubnetIds and vpcSecurityGroupIds when networkMode is \"VPC\"");
   }
-  const memoryEventExpiryDays = props.memoryEventExpiryDays ?? 30;
-  if (memoryEventExpiryDays < 3 || memoryEventExpiryDays > 365) {
-    throw new Error("AgentCoreAgent memoryEventExpiryDays must be between 3 and 365");
+  const memoryEventExpiryDays = props.memoryEventExpiryDays ?? AGENTCORE_LIMITS.memoryEventExpiryDays.default;
+  if (
+    memoryEventExpiryDays < AGENTCORE_LIMITS.memoryEventExpiryDays.min ||
+    memoryEventExpiryDays > AGENTCORE_LIMITS.memoryEventExpiryDays.max
+  ) {
+    throw new Error(
+      `AgentCoreAgent memoryEventExpiryDays must be between ${AGENTCORE_LIMITS.memoryEventExpiryDays.min} and ${AGENTCORE_LIMITS.memoryEventExpiryDays.max}`,
+    );
   }
 
   const runtimeName = toRuntimeIdentifier(props.name);

package/src/composites/bucket-deployment.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from "vitest";
+import { BucketDeployment } from "./bucket-deployment";
+
+describe("BucketDeployment", () => {
+  test("private-by-default: encrypted, public access fully blocked, retained on delete, no policy member", () => {
+    const c = BucketDeployment({});
+    expect(c.bucket).toBeDefined();
+    expect((c as unknown as Record<string, unknown>).bucketPolicy).toBeUndefined();
+
+    const props = (c.bucket as any).props;
+    expect(props.BucketEncryption.props.ServerSideEncryptionConfiguration).toHaveLength(1);
+    expect(props.PublicAccessBlockConfiguration.props).toEqual({
+      BlockPublicAcls: true,
+      BlockPublicPolicy: true,
+      IgnorePublicAcls: true,
+      RestrictPublicBuckets: true,
+    });
+    expect(props.VersioningConfiguration).toBeUndefined();
+    expect(props.WebsiteConfiguration).toBeUndefined();
+
+    const attrs = (c.bucket as any).attributes;
+    expect(attrs.DeletionPolicy).toBe("Retain");
+  });
+
+  test("bucketName threads through, versioning enables Status: Enabled", () => {
+    const c = BucketDeployment({ bucketName: "my-content-bucket", versioned: true });
+    const props = (c.bucket as any).props;
+    expect(props.BucketName).toBe("my-content-bucket");
+    expect(props.VersioningConfiguration.props).toEqual({ Status: "Enabled" });
+  });
+
+  test("removalPolicy: destroy maps to DeletionPolicy: Delete", () => {
+    const c = BucketDeployment({ removalPolicy: "destroy" });
+    expect((c.bucket as any).attributes.DeletionPolicy).toBe("Delete");
+  });
+
+  test("website shape: opens the public-access block, sets WebsiteConfiguration, and attaches a scoped public-read bucketPolicy", () => {
+    const c = BucketDeployment({
+      website: { indexDocument: "index.html", errorDocument: "error.html" },
+    }) as unknown as { bucket: any; bucketPolicy: any };
+
+    const bucketProps = c.bucket.props;
+    expect(bucketProps.PublicAccessBlockConfiguration.props).toEqual({
+      BlockPublicAcls: false,
+      BlockPublicPolicy: false,
+      IgnorePublicAcls: false,
+      RestrictPublicBuckets: false,
+    });
+    expect(bucketProps.WebsiteConfiguration.props).toEqual({
+      IndexDocument: "index.html",
+      ErrorDocument: "error.html",
+    });
+
+    expect(c.bucketPolicy).toBeDefined();
+    expect(c.bucketPolicy.props.Bucket).toBe(c.bucket); // bucket.Ref is the resource instance itself
+    const statement = c.bucketPolicy.props.PolicyDocument.Statement[0];
+    expect(statement).toEqual({ Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: expect.anything() });
+  });
+
+  test("website without errorDocument omits it rather than writing undefined", () => {
+    const c = BucketDeployment({ website: { indexDocument: "index.html" } });
+    const websiteProps = (c.bucket as any).props.WebsiteConfiguration.props;
+    expect(websiteProps).toEqual({ IndexDocument: "index.html" });
+    expect("ErrorDocument" in websiteProps).toBe(false);
+  });
+
+  test("tags pass straight through to the bucket", () => {
+    const c = BucketDeployment({ tags: [{ Key: "env", Value: "prod" }] });
+    expect((c.bucket as any).props.Tags).toEqual([{ Key: "env", Value: "prod" }]);
+  });
+
+  test("defaults escape hatch reaches the bucket (e.g. object-lock)", () => {
+    const c = BucketDeployment({ defaults: { bucket: { ObjectLockEnabled: true } } });
+    expect((c.bucket as any).props.ObjectLockEnabled).toBe(true);
+  });
+
+  test("defaults escape hatch reaches the bucket policy", () => {
+    const c = BucketDeployment({
+      website: { indexDocument: "index.html" },
+      defaults: { bucketPolicy: { Bucket: "explicit-bucket-name" } },
+    }) as unknown as { bucketPolicy: any };
+    expect(c.bucketPolicy.props.Bucket).toBe("explicit-bucket-name");
+  });
+});

package/src/composites/bucket-deployment.ts

@@ -0,0 +1,153 @@
+/**
+ * BucketDeployment — the seeded-bucket shape: an S3 bucket sized to receive
+ * deploy-time content, encrypted and access-blocked by default, its
+ * deletion behaviour and (optionally) its public-read policy declared up
+ * front rather than left to CloudFormation's own defaults.
+ *
+ * `s3deploy.BucketDeployment` is the most-used CDK pattern across the
+ * aws-bench corpus (37 instantiations across 8 apps, chant#1139) and it
+ * names two things CDK bundles together that chant keeps apart on purpose:
+ *
+ *  - The bucket itself: `AWS::S3::Bucket` plus its encryption, access-block
+ *    and (for the static-site shape) website/public-policy configuration.
+ *    That is a fixed set of CloudFormation resources, so it is what this
+ *    composite declares — the same shape `LambdaS3` (../composites) already
+ *    gives a bucket, minus the Lambda trigger wiring.
+ *  - Uploading local files into it at deploy time. CDK does this with a
+ *    Lambda-backed custom resource (`cr.AwsCustomResource`, the same family
+ *    the epic notes maps to chant Ops rather than composites — chant has no
+ *    CloudFormation custom-resource machinery, and inventing one just to
+ *    reproduce a `PutObject` loop would be new plumbing for a solved
+ *    problem). chant already ships this as a deploy-time **capability**,
+ *    `s3-sync` (`../components/apply.ts`'s `createS3SyncCapability`, backed
+ *    by the real `aws s3 sync`/`aws s3 cp` CLI through `CloudExecutor`, with
+ *    the typed step-builder `s3Sync` in `../components/builders.ts`) — it
+ *    was defined for exactly this and, before this composite, had no
+ *    composite pairing it with a bucket to sync into. A component composes
+ *    the two:
+ *
+ *      const seeded = BucketDeployment({ bucketName: Sub`${AWS.StackName}-site` });
+ *      // ...component `deploy` phase:
+ *      s3Sync({ from: "archive:site-build", to: Sub`s3://${seeded.bucket.Ref}` })
+ *
+ * That split — graph-time declaration here, deploy-time action in the
+ * component layer — is the existing precedent (`s3-sync` shipped in #566
+ * unused by any composite until this one), not a new one invented for this
+ * composite.
+ *
+ * "Cleanup" (the epic's third word) is `removalPolicy`, CloudFormation's own
+ * `DeletionPolicy` on the bucket resource. CDK's `autoDeleteObjects` — the
+ * Lambda-backed hook that empties a bucket before CloudFormation is allowed
+ * to delete it — has the same custom-resource shape as content upload and
+ * the same answer: out of scope here, and worth an `s3 rm --recursive`
+ * step ahead of a stack teardown in the component that owns the deploy.
+ */
+import { Composite, mergeDefaults, type Value } from "@intentius/chant";
+import {
+  Bucket,
+  Bucket_BucketEncryption,
+  Bucket_ServerSideEncryptionRule,
+  Bucket_ServerSideEncryptionByDefault,
+  Bucket_PublicAccessBlockConfiguration,
+  Bucket_VersioningConfiguration,
+  Bucket_WebsiteConfiguration,
+  S3BucketPolicy,
+} from "../generated";
+import { Sub } from "../intrinsics";
+
+export interface BucketDeploymentProps {
+  /** `Value<string>`: a name is routinely built with `Sub`/`Ref` (#1366). Omitted lets CloudFormation generate one. */
+  bucketName?: Value<string>;
+  /** Enable S3 object versioning. Default: false. */
+  versioned?: boolean;
+  /**
+   * Static-website hosting: sets `WebsiteConfiguration` and — since a
+   * website bucket is read by anonymous visitors, not IAM principals —
+   * opens the public-access block and attaches a public-read
+   * `S3BucketPolicy` scoped to `s3:GetObject`. Omitted, the bucket stays
+   * fully private, matching every other composite bucket's default
+   * (`LambdaS3`, ../composites).
+   */
+  website?: {
+    indexDocument: string;
+    errorDocument?: string;
+  };
+  /** What CloudFormation does to the bucket when the stack (or the resource) is removed. Default: "retain" — CloudFormation's own default, and the safe one for a bucket a deploy has just put content into. */
+  removalPolicy?: "retain" | "destroy";
+  tags?: Array<{ Key: string; Value: string }>;
+  defaults?: {
+    bucket?: Partial<ConstructorParameters<typeof Bucket>[0]>;
+    bucketPolicy?: Partial<ConstructorParameters<typeof S3BucketPolicy>[0]>;
+  };
+}
+
+export type BucketDeploymentResult =
+  | { bucket: InstanceType<typeof Bucket> }
+  | { bucket: InstanceType<typeof Bucket>; bucketPolicy: InstanceType<typeof S3BucketPolicy> };
+
+export const BucketDeployment = Composite<BucketDeploymentProps>((props) => {
+  const { defaults } = props;
+  const publicRead = props.website !== undefined;
+
+  const encryptionDefault = new Bucket_ServerSideEncryptionByDefault({ SSEAlgorithm: "AES256" });
+  const encryptionRule = new Bucket_ServerSideEncryptionRule({ ServerSideEncryptionByDefault: encryptionDefault });
+  const bucketEncryption = new Bucket_BucketEncryption({ ServerSideEncryptionConfiguration: [encryptionRule] });
+
+  // A ternary, not an `if`, so the block-scoped `new` stays an expression
+  // (EVL002) — the same reasoning eks-cluster.ts's addon slots document.
+  const publicAccessBlock = new Bucket_PublicAccessBlockConfiguration(
+    publicRead
+      ? { BlockPublicAcls: false, BlockPublicPolicy: false, IgnorePublicAcls: false, RestrictPublicBuckets: false }
+      : { BlockPublicAcls: true, BlockPublicPolicy: true, IgnorePublicAcls: true, RestrictPublicBuckets: true },
+  );
+
+  const versioningConfiguration = props.versioned
+    ? new Bucket_VersioningConfiguration({ Status: "Enabled" })
+    : undefined;
+
+  const websiteConfiguration = props.website
+    ? new Bucket_WebsiteConfiguration({
+        IndexDocument: props.website.indexDocument,
+        ...(props.website.errorDocument ? { ErrorDocument: props.website.errorDocument } : {}),
+      })
+    : undefined;
+
+  const bucket = new Bucket(
+    mergeDefaults(
+      {
+        BucketName: props.bucketName,
+        BucketEncryption: bucketEncryption,
+        PublicAccessBlockConfiguration: publicAccessBlock,
+        ...(versioningConfiguration ? { VersioningConfiguration: versioningConfiguration } : {}),
+        ...(websiteConfiguration ? { WebsiteConfiguration: websiteConfiguration } : {}),
+        Tags: props.tags,
+      },
+      defaults?.bucket,
+    ),
+    { DeletionPolicy: props.removalPolicy === "destroy" ? "Delete" : "Retain" },
+  );
+
+  const bucketPolicy = publicRead
+    ? new S3BucketPolicy(
+        mergeDefaults(
+          {
+            Bucket: bucket.Ref,
+            PolicyDocument: {
+              Version: "2012-10-17",
+              Statement: [
+                { Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: Sub`${bucket.Arn}/*` },
+              ],
+            },
+          },
+          defaults?.bucketPolicy,
+        ),
+      )
+    : undefined;
+
+  // Spread rather than a ternary between two object shapes (EksCluster's
+  // addon slots, ../eks-cluster.ts, hit the same union-return typing wall):
+  // a key that is sometimes present, never a key whose value is sometimes
+  // `undefined` — `CompositeMembers`' index signature requires `Declarable`,
+  // not `Declarable | undefined`.
+  return { bucket, ...(bucketPolicy ? { bucketPolicy } : {}) };
+}, "BucketDeployment");