@btc-embedded/cdk-extensions 0.22.21 → 0.22.23

package/AGENTS.md

@@ -0,0 +1,252 @@
+# AGENTS.md — Developer & Agentic Coding Guide
+
+AWS CDK construct library (`@btc-embedded/cdk-extensions`). **Projen-managed**: never edit
+`package.json`, `.gitignore`, `.eslintrc.json`, or `tsconfig.json` directly — modify
+`.projenrc.ts` and run `npx projen` to regenerate them.
+
+---
+
+## Build / Lint / Test Commands
+
+```bash
+yarn build          # Full pipeline: compile → bundle → test → package
+yarn compile        # jsii compilation only (produces lib/)
+yarn typecheck      # Type-check src + test without emitting (tsc --noEmit)
+yarn test           # Run all Jest tests
+yarn test <pattern> # Run a single test file or name pattern (args forwarded to Jest)
+yarn test:watch     # Jest in watch mode
+yarn eslint         # Run ESLint interactively
+yarn eslint:ci      # Lint with CI reporter, fail on any warning
+yarn bundle         # Bundle all Lambda handlers + CLI with esbuild
+yarn integ          # Run integration test snapshots
+yarn integ:update   # Update integration test snapshots
+```
+
+### Running a Single Test
+
+```bash
+# By filename pattern
+yarn test S3Bucket
+
+# By path
+yarn test test/constructs/S3Bucket.test.ts
+
+# By test name pattern
+yarn test S3Bucket --testNamePattern "developer stack"
+```
+
+Type errors in tests are caught by `yarn typecheck`, not by Jest itself
+(`diagnostics: false` in ts-jest keeps test runs fast).
+
+---
+
+## Project Structure
+
+```
+src/
+  constructs/     Higher-level CDK constructs (S3Bucket, SecureRestApi, EventPipe, …)
+  extensions/     ECS ServiceExtension subclasses
+  platform/       Base-platform constructs (VPC, ECS cluster, Aurora, Cognito, …)
+  stacks/         ApplicationStack base class
+  utils/          StackParameter, BasePlatformStackResolver, helpers
+  cli/            catnip CLI (excluded from jsii; bundled with esbuild)
+test/             Jest tests — mirrors src/ layout
+assets/cli/       Bundled CLI binary
+docs/             API docs, ADRs (docs/adr/), RFCs (docs/rfc/), construct docs
+```
+
+---
+
+## Architecture Patterns
+
+### Platform / Application Stack Split
+
+- **Base Platform Stack** — deployed once per environment; holds shared infra (VPC, ECS
+  cluster, Aurora, Cognito, EFS, …). Lives in `src/platform/`.
+- **Application Stack** — per-service stacks that import from the base platform. Constructs
+  live in `src/constructs/` and `src/extensions/`.
+
+### `fromBasePlatform()` Pattern
+
+Every platform construct exposes a static `fromBasePlatform(scope, id, basePlatformStackName?)`
+that reconstructs the construct from CloudFormation `Fn::ImportValue` exports.
+
+```typescript
+static fromBasePlatform(scope: Construct, id: string, stackName?: string): IVpc {
+  class Import extends Construct implements IVpc {
+    readonly fqdn = Vpc.fqdnParameter.import(scope, stackName);
+  }
+  return new Import(scope, id);
+}
+```
+
+### `StackParameter` — Cross-Stack References
+
+Wraps `CfnOutput` (export) and `Fn.importValue` (import) with structured naming:
+`{stackName}:{prefix}[-v{version}]:{key}` — e.g. `platform-stack:cognito-v2:user-pool-id`.
+Declare as `private static readonly` on the owning class; call `.export(this, value)` in the
+constructor and `.import(scope, stackName)` in `fromBasePlatform`.
+
+### `BasePlatformStackResolver` — Context Propagation
+
+`ApplicationStack` stores `basePlatformStackName` in CDK context under
+`cdk-extensions:basePlatformStackName`. `BasePlatformStackResolver.resolve(scope, propsValue?)`
+reads it as a fallback, so child constructs can omit the prop when inside an `ApplicationStack`.
+
+### Abstract Base Class Pattern for Platform Constructs
+
+1. `interface IFoo` — public contract
+2. `abstract class FooBase extends Construct implements IFoo` — shared methods
+3. `class Foo extends FooBase` — creates resources, exports parameters
+4. `fromBasePlatform()` returns `new class Import extends FooBase { … }()` — imports values
+
+### ECS Service Extensions
+
+Extensions extend `ServiceExtension`. Key lifecycle hooks:
+
+- `prehook(parent, scope)` — resolve references before service creation
+- `addHooks()` — register `ContainerMutatingHook` instances
+- `modifyServiceProps(props)` — modify ECS service props
+- `useTaskDefinition(td)` — add containers, volumes, IAM policies
+- `useService(service)` — post-creation wiring
+
+---
+
+## JSII Constraints
+
+JSII enforces a strict subset of TypeScript. Violating these causes `jsii` compilation errors.
+
+- **No** `Omit`, `Pick`, `Required`, `Partial`, complex type aliases, or property re-declaration
+  in interfaces
+- **No** `require()` imports (use ES module `import`)
+- Extend interfaces with `extends`; never re-declare inherited properties
+
+**Workaround pattern:**
+
+```typescript
+// ✅ Correct: extend without re-declaring; validate at runtime
+export interface MyProps extends BaseProps {}
+
+constructor(props: MyProps) {
+  if (!props.optionalField) throw new Error("MyConstruct: 'optionalField' is required");
+  super({ cpu: props.cpu }); // No ! needed after validation
+}
+```
+
+---
+
+## Code Style Guidelines
+
+### Naming
+
+| Entity                     | Convention                           | Example                                   |
+| -------------------------- | ------------------------------------ | ----------------------------------------- |
+| Classes / constructs       | PascalCase                           | `ApplicationContainer`, `BTCLogGroup`     |
+| Construct logical IDs      | PascalCase                           | `new Certificate(this, "Certificate", …)` |
+| Props interfaces           | `<Class>Props`                       | `EcsClusterProps`                         |
+| Abstract base classes      | `<Class>Base`                        | `CognitoUserPoolBase`                     |
+| Import interfaces          | `I<Class>`                           | `IVpc`, `IEfsFileSystem`                  |
+| Enums                      | PascalCase name, UPPER_CASE values   | `EfsAccessMode.READ_ONLY`                 |
+| Module-level constants     | `UPPER_CASE_SNAKE`                   | `BASE_PLATFORM_STACK_NAME_CONTEXT_KEY`    |
+| Functions / methods        | camelCase                            | `kebabCase()`, `resolveBasePlatform()`    |
+| Resource names / log paths | kebab-case via `kebabCase()` utility | `/${app}/${kebabCase(id)}`                |
+
+### Imports
+
+Order (enforced by `import/order` lint rule): **builtin → external**, alphabetized
+ascending, case-insensitive. Use namespace imports (`import * as ecs from "aws-cdk-lib/aws-ecs"`)
+when many items from a module are needed.
+
+```typescript
+import { Construct } from "constructs";
+import * as cdk from "aws-cdk-lib";
+import * as ecs from "aws-cdk-lib/aws-ecs";
+import { ServiceExtension } from "@aws-cdk-containers/ecs-service-extensions";
+
+import { StackParameter } from "../utils";
+import { kebabCase } from "./common";
+```
+
+### Types and Interfaces
+
+- Public API props: `interface` with `readonly` properties
+- Explicit return types on all `public` methods; infer on private helpers
+- Prefer `??` (nullish coalescing) and ternaries over `if/else` for simple defaults
+- No `!` non-null assertions after runtime validation (TypeScript control flow is trusted)
+
+### Error Handling
+
+```typescript
+// Constructor validation format
+if (!props.cpu) throw new Error("ApplicationContainer: 'cpu' is required");
+if (!/^[a-z][a-z0-9-]+$/.test(prefix)) {
+  throw new Error(`prefix '${prefix}' must be kebab-case (like 'foo-bar')`);
+}
+```
+
+### Member Ordering (enforced by ESLint)
+
+`public static` fields → `public static` methods → `protected static` → `private static` →
+instance fields → constructor → instance methods.
+
+### Formatting (Prettier defaults via eslint-plugin-prettier)
+
+2-space indent, double quotes, trailing commas, semicolons. Formatting errors surface as ESLint
+errors — run `yarn eslint` to auto-fix.
+
+### General
+
+- `const` for immutable bindings; `let` where reassignment is needed
+- Spread for prop merging: `{ ...props, override: value }`
+- Minimal inline comments — only for non-obvious behaviour
+- No `require()` calls anywhere in `src/` (enforced by `@typescript-eslint/no-require-imports`)
+
+---
+
+## Testing Philosophy
+
+- Use `Template.fromStack(stack)` for CloudFormation resource assertions
+- One general usage test + targeted corner cases — avoid redundant coverage
+- Remove tests that are fully covered by a higher-level test
+- **Workflow**: write comprehensive tests first → get approval → implement → simplify tests
+  as needed
+
+```typescript
+import { App, Stack } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+
+test("creates S3 bucket with versioning", () => {
+  const app = new App();
+  const stack = new Stack(app, "TestStack");
+  new S3Bucket(stack, "Bucket", { versioned: true });
+  const template = Template.fromStack(stack);
+  template.hasResourceProperties("AWS::S3::Bucket", {
+    VersioningConfiguration: { Status: "Enabled" },
+  });
+});
+```
+
+---
+
+## Local Testing with yalc
+
+```bash
+# In cdk-extensions — publish locally
+yarn build && npx yalc publish
+
+# In consumer project — link
+npx yalc add @btc-embedded/cdk-extensions && yarn install
+
+# After further changes in cdk-extensions
+yarn build && npx yalc push
+```
+
+---
+
+## Commit Format
+
+```
+<type>: <description>
+```
+
+Types: `feat`, `feat!` (breaking), `fix`, `refactor`, `chore`, `misc`, `test`