vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/aws-cdk/references/construct-patterns.md

@@ -0,0 +1,315 @@
+# Construct Patterns
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Scope and Construct IDs](#scope-and-construct-ids)
+- [Choosing Construct Levels](#choosing-construct-levels)
+- [Mixing L1 and L2](#mixing-l1-and-l2)
+- [Cross-Stack References](#cross-stack-references)
+- [Creating Custom Constructs](#creating-custom-constructs)
+- [Testing CDK Infrastructure](#testing-cdk-infrastructure)
+
+---
+
+## Overview
+
+This reference covers construct selection, composition, cross-stack wiring, and testing patterns. It provides decision frameworks for choosing construct levels, mixing them safely, passing references across stacks, building custom constructs, and verifying infrastructure with assertions.
+
+---
+
+## Scope and Construct IDs
+
+Every construct is created with `new SomeConstruct(scope, id, props?)`. The first two arguments are not interchangeable boilerplate — misusing them is a common review finding.
+
+### Scope (first argument)
+
+Inside a construct's `constructor`, you MUST pass `this` as the scope of child constructs — NOT the incoming `scope` argument:
+
+```typescript
+// ❌ INCORRECT — child parented to the wrong node
+export class MyConstruct extends Construct {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    new ChildConstruct(scope, 'Child');   // wrong: uses 'scope'
+  }
+}
+
+// ✅ CORRECT
+export class MyConstruct extends Construct {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    new ChildConstruct(this, 'Child');     // 'this' is the parent
+  }
+}
+```
+
+Passing `this` makes the child a child of the current construct, which is almost always the intent. A scope other than `this` is legitimate only when it comes from a function parameter or a local variable used to group constructs (e.g. in `App` or helper/test stacks).
+
+### Construct ID (second argument)
+
+The construct ID is the locally unique identifier within a scope. The IDs between a CloudFormation resource and its containing `Stack` are concatenated into the resource's **logical ID** — and changing a logical ID replaces the resource.
+
+- Construct IDs SHOULD be short and to the point.
+- You SHOULD NOT interpolate variables into a construct ID: if the variable's value changes, the logical ID changes and the resource is replaced. Legitimate exceptions (constructs created in a loop; an intentional, conditional replacement) MUST be annotated with a comment explaining why.
+- Construct IDs only need to be unique within their scope. They SHOULD NOT repeat project, region, or stage names already present higher in the construct tree.
+
+---
+
+## Choosing Construct Levels
+
+You SHOULD prefer L2 constructs as the default choice. They provide sensible defaults, grant methods, and metric helpers.
+
+### Decision tree
+
+| Need                                   | Construct type                             |
+| -------------------------------------- | ------------------------------------------ |
+| Pure logic, no AWS resource            | Plain TypeScript/Python class              |
+| Single resource with stricter defaults | Extend the L2 class (is-a)                 |
+| Composition of multiple resources      | Extend `Construct` (has-a) — this is an L3 |
+| Organization-wide policy enforcement   | `Aspect`                                   |
+
+### When L1 is viable
+
+L1 (`Cfn*`) constructs are acceptable when no L2 exists or when you need a property the L2 does not expose. You SHOULD combine L1 with Mixins, Facades, or `I<Resource>Ref` interfaces to retain type safety and grant support.
+
+### When using L3
+
+L3 constructs provision multiple resources behind a single API. You MUST read what they provision (check the source or `cdk synth` output) before using them in production. Hidden resources may have cost, security, or operational implications.
+
+### When an L2 doesn't expose a property
+
+Use this escalation ladder — prefer the first option that works:
+
+1. **Cfn<Resource>PropsMixin** (preferred) — type-safe, applied via `.with()`:
+
+   ```typescript
+   import { CfnBucketPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-s3';
+   new s3.Bucket(this, 'Bucket').with(new CfnBucketPropsMixin({
+     analyticsConfigurations: [{ id: 'full', prefix: '' }],
+   }));
+   ```
+
+2. **`addPropertyOverride`** — untyped, string-keyed last resort:
+
+   ```typescript
+   const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;
+   cfnBucket.addPropertyOverride('AnalyticsConfigurations', [{ Id: 'full', Prefix: '' }]);
+   ```
+
+---
+
+## Mixing L1 and L2
+
+When a stack contains both L1 and L2 constructs, you MUST use `I<Resource>Ref` interfaces and Facades to bridge them — do not pass L1 property types to L2 props or vice versa, as their types are not interchangeable.
+
+### I<Resource>Ref interfaces (e.g. IBucketRef)
+
+Both L1 and L2 constructs implement `I<Resource>Ref`-style interfaces (e.g., `IBucketRef`, `IFunctionRef`). Use these interfaces as prop types to accept either level:
+
+```typescript
+interface MyProps {
+  readonly bucket: s3.IBucketRef;
+}
+```
+
+### Facades for L1 grants
+
+L1 constructs lack `grant*()` methods. You SHOULD wrap them with `fromCfn<Resource>()` or `from<Resource>Attributes()` to get an L2 interface:
+
+```typescript
+const cfnTable = new dynamodb.CfnTable(this, 'Table', { /* ... */ });
+const table = dynamodb.Table.fromTableArn(this, 'TableRef', cfnTable.attrArn);
+table.grantReadData(myFunction);
+```
+
+### Escalation ladder
+
+When you need to customize a resource, follow this order (least invasive first):
+
+1. L2 prop — use the built-in property if available.
+2. Mixin — add behavior via a helper function.
+3. `Cfn<Resource>PropsMixin` — type-safe L1 prop injection.
+4. `node.defaultChild` — access the underlying L1 construct.
+5. `addPropertyOverride` — override arbitrary CloudFormation properties.
+
+You SHOULD exhaust each level before moving to the next.
+
+---
+
+## Cross-Stack References
+
+### Same app, same region
+
+Pass construct references via stack props. CDK automatically creates CloudFormation exports and imports:
+
+```typescript
+interface ConsumerProps extends cdk.StackProps {
+  readonly bucket: s3.IBucket;
+}
+
+class ConsumerStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props: ConsumerProps) {
+    super(scope, id, props);
+    props.bucket.grantRead(myFunction);
+  }
+}
+```
+
+### Cross-region or cross-account (same app)
+
+Enable `crossRegionReferences: true` on the consuming stack and use explicit physical names on shared resources:
+
+```typescript
+new ConsumerStack(app, 'Consumer', {
+  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+  crossRegionReferences: true,
+  bucket: producerStack.bucket,
+});
+```
+
+### Different apps
+
+When stacks are in different CDK apps, automatic exports do not work. You MUST use one of:
+
+- `CfnOutput` + `Fn.importValue`:
+
+  ```typescript
+  // Producer app
+  new cdk.CfnOutput(this, 'BucketArn', { value: bucket.bucketArn, exportName: '$EXPORT_NAME' });
+
+  // Consumer app
+  const arn = cdk.Fn.importValue('$EXPORT_NAME');
+  ```
+
+- SSM Parameter Store for decoupled lookups.
+
+### Fixing cycles
+
+If cross-stack references create a dependency cycle, you MUST extract the shared resource into a third stack so that dependencies flow one way.
+
+---
+
+## Creating Custom Constructs
+
+### Extend L2 (is-a)
+
+Use when you want a single resource with stricter defaults:
+
+```typescript
+export class SecureBucket extends s3.Bucket {
+  constructor(scope: Construct, id: string, props?: s3.BucketProps) {
+    super(scope, id, {
+      encryption: s3.BucketEncryption.S3_MANAGED,
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      enforceSSL: true,
+      ...props,
+    });
+  }
+}
+```
+
+### Compose L3 (has-a)
+
+Use when you combine multiple resources behind a single API:
+
+```typescript
+export class ApiWithQueue extends Construct {
+  public readonly queue: sqs.Queue;
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    this.queue = new sqs.Queue(this, 'Queue');
+    // ... additional resources
+  }
+}
+```
+
+### Stable logical IDs
+
+The default child ID determines the CloudFormation logical ID. You MUST NOT change construct IDs after deployment — this causes resource replacement. Use the `Default` child ID convention for the primary resource in an L3.
+
+### Escape via defaultChild
+
+When extending an L2, you can access the underlying CFN resource:
+
+```typescript
+const cfn = this.node.defaultChild as s3.CfnBucket;
+cfn.addPropertyOverride('$PROPERTY_PATH', '$VALUE');
+```
+
+---
+
+## Testing CDK Infrastructure
+
+### Fine-grained assertions
+
+Use `Template.fromStack()` to assert on specific resources:
+
+```typescript
+const template = Template.fromStack(myStack);
+
+template.hasResourceProperties('AWS::SQS::Queue', {
+  VisibilityTimeout: 300,
+});
+```
+
+### Partial matching
+
+Use `Match.*` helpers for flexible assertions:
+
+```typescript
+template.hasResourceProperties('AWS::Lambda::Function', {
+  Runtime: Match.stringLikeRegexp('nodejs'),
+  Environment: Match.objectLike({
+    Variables: Match.objectLike({
+      TABLE_NAME: Match.anyValue(),
+    }),
+  }),
+});
+```
+
+### Snapshot tests
+
+Capture the full template and compare against a stored baseline:
+
+```typescript
+expect(template.toJSON()).toMatchSnapshot();
+```
+
+You SHOULD use snapshot tests to detect unintended drift but MUST NOT rely on them as the sole testing strategy — they are brittle and hard to review.
+
+### Logical ID stability tests
+
+Assert that critical resource logical IDs remain stable to prevent accidental replacement:
+
+```typescript
+template.hasResource('AWS::DynamoDB::Table', {
+  // Verifying the resource exists with this logical ID
+});
+```
+
+### Integration tests
+
+Use `@aws-cdk/integ-tests-alpha` for tests that deploy real infrastructure:
+
+```typescript
+const integ = new IntegTest(app, 'MyIntegTest', {
+  testCases: [myStack],
+});
+
+integ.assertions
+  .awsApiCall('DynamoDB', 'DescribeTable', { TableName: '$TABLE_NAME' })
+  .assertAtPath('Table.TableStatus', ExpectedResult.stringLikeRegexp('ACTIVE'));
+```
+
+Integration tests SHOULD be run in a dedicated test account. They MUST NOT run against production.
+
+### Application best practices
+
+- Make decisions at synth time — use explicit `env` to enable synth-time logic.
+- Use generated physical names (CDK default) unless cross-stack or cross-app references require explicit names.
+- Set explicit `removalPolicy` and `logRetention` on every resource.
+- Separate stateful resources (databases, buckets) into their own stack.
+- Commit `cdk.context.json` to version control for reproducible synth.
+- Use `grant*()` methods for IAM instead of hand-written policy statements.

package/dist/global-skills/aws-cdk/references/import-and-migrate.md

@@ -0,0 +1,184 @@
+# Import and Migrate Reference
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Read-Only References (from* Methods)](#read-only-references-from-methods)
+- [Full Resource Adoption (cdk import)](#full-resource-adoption-cdk-import)
+- [CI-Friendly Import (--import-existing-resources)](#ci-friendly-import---import-existing-resources)
+- [Migrating with cdk migrate](#migrating-with-cdk-migrate)
+  - [From an Existing Stack](#from-an-existing-stack)
+  - [From a Template File](#from-a-template-file)
+  - [From a Live Account Scan](#from-a-live-account-scan)
+  - [Migration Constraints](#migration-constraints)
+  - [First Deploy After Migration](#first-deploy-after-migration)
+  - [Incremental Refactoring](#incremental-refactoring)
+- [Post-Import Verification](#post-import-verification)
+
+---
+
+## Overview
+
+CDK provides three mechanisms for referencing or adopting existing AWS resources,
+plus a migration tool for converting existing CloudFormation stacks or live
+infrastructure into CDK code. The right mechanism depends on whether you need
+read-only access or full lifecycle management.
+
+| Mechanism                        | Use Case                          | Lifecycle Control |
+|----------------------------------|-----------------------------------|-------------------|
+| `from*` methods                  | Reference existing resources      | Read-only         |
+| `cdk import`                     | Adopt resources into a stack      | Full (interactive)|
+| `--import-existing-resources`    | Adopt resources in CI             | Full (automated)  |
+| `cdk migrate`                    | Convert stacks/infra to CDK code  | Full              |
+
+---
+
+## Read-Only References (from* Methods)
+
+Use `from*` static methods (e.g., `Bucket.fromBucketName()`,
+`Vpc.fromLookup()`) to reference existing resources without managing their
+lifecycle:
+
+```typescript
+const bucket = s3.Bucket.fromBucketName(this, 'ImportedBucket', '$BUCKET_NAME');
+const vpc = ec2.Vpc.fromLookup(this, 'ImportedVpc', { vpcId: '$VPC_ID' });
+```
+
+Constraints:
+
+- `from*` references are **read-only** — CDK MUST NOT attempt to modify or
+  delete these resources.
+- `fromLookup` methods require the `env` property (account and region) to be
+  set on the stack. They perform API calls at synth time and cache results in
+  `cdk.context.json`.
+- `cdk.context.json` SHOULD be committed to version control so that synth is
+  reproducible without network access.
+
+---
+
+## Full Resource Adoption (cdk import)
+
+`cdk import` adopts existing resources into a CDK stack so CDK fully manages their lifecycle.
+
+**Interactive (default):**
+
+```bash
+cdk import $STACK_NAME
+```
+
+The CLI prompts for each resource's physical identifier (bucket name, table name, etc.).
+
+**Non-interactive (CI-friendly):**
+
+```bash
+# First, generate a mapping template:
+cdk import $STACK_NAME --record-resource-mapping mapping.json
+
+# Fill in the physical resource IDs, then import:
+cdk import $STACK_NAME --resource-mapping mapping.json
+```
+
+Workflow:
+
+1. Add the construct to your CDK code matching the existing resource's properties
+2. Run `cdk import $STACK_NAME` (interactive) or with `--resource-mapping` (CI)
+3. CloudFormation executes an import change set — no resource is created
+
+Constraints:
+
+- Not all CloudFormation resource types support import
+- Resources that depend on each other MUST be imported together or in the correct order
+- The only allowed changes during import are additions of the imported resources
+
+---
+
+## CI-Friendly Import (--import-existing-resources)
+
+For non-interactive, CI-friendly imports, use the `--import-existing-resources` flag during a normal deploy:
+
+```bash
+cdk deploy $STACK_NAME --import-existing-resources
+```
+
+The CLI matches resources in the synthesized template against existing unmanaged resources in the account by their **custom physical name** (e.g., explicit `bucketName`, `tableName`, `roleName`). Matches are imported instead of created.
+
+**Constraints:**
+
+- You MUST set explicit physical names on resources you want to import — auto-generated names cannot be matched
+- The resource MUST be unmanaged (not already part of another CloudFormation stack)
+- Not every resource type supports CloudFormation import
+- Supports mixed operations — you can add new resources AND import existing ones in the same deploy
+
+**When to prefer over `cdk import`:**
+
+- CI/CD pipelines where interactive prompts are not possible
+- Rolling out a new stack that overlaps with existing resources
+- Mixed operations (new + imported resources in one change set)
+
+---
+
+## Migrating with cdk migrate
+
+`cdk migrate` generates CDK code from existing CloudFormation stacks, template
+files, or live account scans.
+
+### From an Existing Stack
+
+```bash
+cdk migrate --from-stack --stack-name $STACK_NAME
+```
+
+### From a Template File
+
+```bash
+cdk migrate --from-path $TEMPLATE_FILE_PATH --stack-name $STACK_NAME
+```
+
+### From a Live Account Scan
+
+```bash
+cdk migrate --from-scan --stack-name $STACK_NAME
+```
+
+### Migration Constraints
+
+- Output is **L1 constructs only** (`Cfn*` classes). Higher-level L2/L3
+  constructs are NOT generated.
+- Only a **single stack** can be migrated per invocation.
+- **Assets are not migrated** — inline code, S3 references, and Docker images
+  MUST be handled manually after migration.
+
+### First Deploy After Migration
+
+A `migrate.json` file is generated alongside the CDK code. This file is
+REQUIRED for the first deployment after migration — it tells CloudFormation to
+import the existing resources rather than creating new ones.
+
+```bash
+cdk deploy $STACK_NAME
+```
+
+The `migrate.json` file is consumed automatically on the first deploy and MAY
+be removed afterward.
+
+### Incremental Refactoring
+
+After migration, incrementally refactor L1 constructs to L2/L3 constructs:
+
+1. Replace one `Cfn*` resource at a time with its L2/L3 equivalent.
+2. Run `cdk diff` after each change to verify no unintended replacements.
+3. Deploy incrementally to validate each refactoring step.
+
+---
+
+## Post-Import Verification
+
+After importing or migrating resources, the following steps MUST be performed:
+
+1. **Verify drift** — Run `cdk drift $STACK_NAME` to confirm the imported
+   resource state matches the CDK definition.
+2. **Protect logical IDs** — Logical ID changes after import will cause
+   resource replacement. Lock logical IDs with unit tests or use
+   `overrideLogicalId()` where necessary.
+3. **Run `cdk diff`** — Confirm no unexpected changes are pending before the
+   next deployment.

package/dist/global-skills/aws-cdk/references/refactor-and-prevent-replacement.md

@@ -0,0 +1,198 @@
+# Refactor and Prevent Replacement Reference
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Detecting Replacement](#detecting-replacement)
+- [Common Causes](#common-causes)
+- [Using cdk refactor](#using-cdk-refactor)
+  - [Workflow](#workflow)
+  - [Resolving Ambiguity](#resolving-ambiguity)
+  - [Constraints](#constraints)
+- [Prevention Techniques](#prevention-techniques)
+  - [Do Not Hardcode Physical Names](#do-not-hardcode-physical-names)
+  - [Use Default as Child ID](#use-default-as-child-id)
+  - [Use cdk refactor for Moves and Renames](#use-cdk-refactor-for-moves-and-renames)
+  - [Use overrideLogicalId](#use-overridelogicalid)
+  - [Lock Logical IDs with Unit Tests](#lock-logical-ids-with-unit-tests)
+  - [Isolate Stateful Resources with RETAIN](#isolate-stateful-resources-with-retain)
+- [Protecting Stateful Resources](#protecting-stateful-resources)
+
+---
+
+## Overview
+
+Resource replacement occurs when CloudFormation determines it must delete and
+recreate a resource instead of updating it in place. For stateful resources
+(databases, S3 buckets, encryption keys), replacement causes **data loss**.
+This reference covers detection, common causes, and prevention techniques.
+
+---
+
+## Detecting Replacement
+
+Use `cdk diff` to detect pending replacements before deploying:
+
+```bash
+cdk diff $STACK_NAME
+```
+
+In the output, look for:
+
+- `[-]` markers indicating resource deletion.
+- `[~]` markers with "requires replacement" annotations on specific properties.
+
+Any resource showing "requires replacement" MUST be investigated before
+deploying. MUST NOT deploy when `cdk diff` shows replacement of stateful
+resources unless the replacement is intentional and data has been backed up.
+
+---
+
+## Common Causes
+
+Resource replacement is typically caused by:
+
+1. **Construct ID changes** — Renaming a construct or moving it to a different
+   scope changes its CloudFormation logical ID, which CloudFormation treats as
+   a delete + create.
+
+2. **Immutable CloudFormation properties** — Certain resource properties cannot
+   be updated in place (e.g., DynamoDB table name, RDS engine). Changing these
+   forces replacement.
+
+3. **Hardcoded physical names** — If a resource has a hardcoded physical name
+   and the logical ID changes, CloudFormation cannot create the new resource
+   because the name is already taken, causing a deployment failure.
+
+---
+
+## Using cdk refactor
+
+`cdk refactor` safely moves or renames constructs without triggering resource
+replacement. It is currently an unstable feature.
+
+### Workflow
+
+1. **Deploy a baseline** — Ensure the current state is deployed and clean.
+
+   ```bash
+   cdk deploy $STACK_NAME
+   ```
+
+2. **Edit the code** — Perform moves and renames only. MUST NOT change resource
+   properties in the same step.
+
+3. **Run refactor** — Generate the resource mapping:
+
+   ```bash
+   cdk refactor --unstable=refactor
+   ```
+
+4. **Confirm the mapping** — Review the proposed logical ID mappings.
+
+5. **Deploy** — Apply the refactoring:
+
+   ```bash
+   cdk deploy $STACK_NAME
+   ```
+
+6. **Deploy property changes separately** — Any property changes MUST be made
+   and deployed in a subsequent step, after the refactor deploy succeeds.
+
+### Resolving Ambiguity
+
+When `cdk refactor` cannot determine the mapping (e.g., multiple resources of
+the same type were moved), provide an override JSON file to resolve the
+ambiguity.
+
+### Constraints
+
+- Refactoring MUST stay within the same environment (account + region).
+- Only moves and renames are supported — property changes MUST NOT be combined
+  with refactoring in the same deployment.
+
+---
+
+## Prevention Techniques
+
+### Do Not Hardcode Physical Names
+
+Physical resource names (bucket names, table names, queue names) SHOULD NOT be
+hardcoded. Let CloudFormation generate unique names. Hardcoded names prevent
+CloudFormation from performing replacement when needed and cause name-collision
+failures.
+
+### Use Default as Child ID
+
+When extracting inline resources into a separate construct, use `'Default'` as
+the child construct ID to preserve the original logical ID:
+
+```typescript
+// Before: resource defined directly in the stack
+new s3.Bucket(this, 'MyBucket', { ... });
+
+// After: extracted into a construct — use 'Default' to keep the same logical ID
+class MyConstruct extends Construct {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    new s3.Bucket(this, 'Default', { ... });
+  }
+}
+new MyConstruct(this, 'MyBucket');
+```
+
+### Use cdk refactor for Moves and Renames
+
+When moving or renaming constructs, use `cdk refactor --unstable=refactor`
+instead of manually tracking logical IDs. See [Using cdk refactor](#using-cdk-refactor).
+
+### Use overrideLogicalId
+
+As an alternative to `cdk refactor`, explicitly set the logical ID to preserve
+it across code changes:
+
+```typescript
+const bucket = new s3.Bucket(this, 'NewId', { ... });
+(bucket.node.defaultChild as s3.CfnBucket).overrideLogicalId('$ORIGINAL_LOGICAL_ID');
+```
+
+This approach SHOULD be used sparingly — it creates a maintenance burden and
+bypasses CDK's automatic ID generation.
+
+### Lock Logical IDs with Unit Tests
+
+Write unit tests that assert the logical IDs of stateful resources. This
+prevents accidental ID changes from reaching deployment:
+
+```typescript
+test('stateful resource logical IDs are stable', () => {
+  const template = Template.fromStack($STACK);
+  const tables = template.findResources('AWS::DynamoDB::Table');
+  expect(Object.keys(tables)).toContain('$EXPECTED_LOGICAL_ID');
+});
+```
+
+### Isolate Stateful Resources with RETAIN
+
+Place stateful resources in a dedicated stack with the `RETAIN` removal policy.
+This ensures that even if the stack is deleted, the resources are preserved:
+
+```typescript
+new s3.Bucket(this, 'DataBucket', {
+  removalPolicy: RemovalPolicy.RETAIN,
+});
+```
+
+---
+
+## Protecting Stateful Resources
+
+A defense-in-depth approach SHOULD be used for stateful resources:
+
+1. **RETAIN removal policy** — Prevents data loss on stack deletion.
+2. **Dedicated stack** — Isolates stateful resources from frequently changing
+   application stacks.
+3. **Logical ID unit tests** — Catches accidental renames before deployment.
+4. **`cdk diff` review** — MUST be reviewed before every production deployment.
+5. **No hardcoded physical names** — Avoids name-collision failures during
+   replacement.