@alma-cdk/project 1.0.1 → 1.0.3

package/.jsii

@@ -3672,7 +3672,7 @@
   },
   "name": "@alma-cdk/project",
   "readme": {
-    "markdown": "<div align=\"center\">\n\t<br/>\n\t<br/>\n  <h1>\n\t<img width=\"300\" src=\"assets/alma-cdk-project.svg\" alt=\"Alma CDK Project\" />\n  <br/>\n  <br/>\n  </h1>\n\n  ![NPM License](https://img.shields.io/npm/l/%40alma-cdk%2Fproject)\n  [![release](https://github.com/alma-cdk/project/actions/workflows/release.yml/badge.svg)](https://github.com/alma-cdk/project/actions/workflows/release.yml)\n\n  ```sh\n  npm i -D @alma-cdk/project\n  ```\n\n  <div align=\"left\">\n\n  Opinionated CDK “framework” with constructs & utilities for:\n  - deploying multiple environments to multiple accounts (with many-to-many relationship)\n  - managing account configuration through standardized props (no more random config files)\n  - querying account and/or environment specific information within your CDK code\n  - enabling dynamic & short-lived “feature-environments”\n  - enabling well-defined tagging\n  - providing structure & common conventions to CDK projects\n  - choosing the target account & environment by passing in runtime context:\n\n    ```sh\n    npx cdk deploy -c account=dev -c environment=feature/abc-123\n    ```\n    ... which means you don't need to define all the possibile environments ahead of time!\n\n  </div>\n  <br/>\n</div>\n\n\n## Account Strategies\n\nDepending on the use case, you may choose a configuration between 1-3 AWS accounts with the following environments:\n\n\n1. **Shared account (`shared`)**:\n\n    ![default-multi](assets/accounts-1x.svg)\n    <br/>\n\n2. **Multi-account (`dev`+`prod`)**_– RECOMMENDED_:\n\n    ![default-multi](assets/accounts-2x.svg)\n    <br/>\n\n<br/>\n</details>\n\n3. **Multi-account (`dev`+`preprod`+`prod`)**:\n\n    ![default-multi](assets/accounts-3x.svg)\n    <br/>\n\n<br/>\n\n## Getting Started\n\nSteps required to define a _environmental_ project resources; At first, it might seem complex but once you get into the habbit of defining your projects this way it starts to make sense:\n\n1. Choose your [Account Strategy](#account-strategies)\n\n2. Initialize a new `Project` instead of `cdk.App`:\n\n    ```ts\n    // bin/app.ts\n    import { Project, AccountStrategy } from '@alma-cdk/project';\n\n    const project = new Project({\n      // Basic info, you could also read these from package.json if you want\n      name: 'my-cool-project',\n      author: {\n        organization: 'Acme Corp',\n        name: 'Mad Scientists',\n        email: 'mad.scientists@acme.example.com',\n      },\n\n      // If not set, defaults to one of: $CDK_DEFAULT_REGION, $AWS_REGION or us-east-1\n      defaultRegion: 'eu-west-1',\n\n      // Configures the project to use 2 AWS accounts (recommended)\n      accounts: AccountStrategy.two({\n        dev: {\n          id: '111111111111',\n          config: {\n            // whatever you want here as [string]: any\n            baseDomain: 'example.net',\n          },\n        },\n        prod: {\n          id: '222222222222',\n          config: {\n            // whatever you want here as [string]: any\n            baseDomain: 'example.com',\n          },\n        },\n      }),\n    })\n    ```\n\n3. Define a stack which `extends SmartStack` with resources:\n    ```ts\n    // lib/my-stack.ts\n    import { Construct } from 'constructs';\n    import { StackProps, RemovalPolicy } from 'aws-cdk-lib';\n    import { SmartStack, Name, UrlName, PathName, EC } from '@alma-cdk/project';\n\n    export class MyStack extends SmartStack {\n      constructor(scope: Construct, id: string, props: StackProps) {\n        super(scope, id, props);\n\n        new dynamodb.Table(this, 'Table', {\n          removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,\n\n          tableName: Name.it(this, 'MyTable'),\n          partitionKey: {\n            type: dynamodb.AttributeType.STRING,\n            name: 'pk',\n          },\n          // StagingMyTable\n        });\n\n        new events.EventBus(this, 'EventBus', {\n          eventBusName: Name.withProject(this, 'MyEventBus'),\n          // MyCoolProjectStagingMyEventBus\n        });\n\n        new s3.Bucket(this, 'Bucket', {\n\n          removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,\n          autoDeleteObjects: EC.isStable(this) ? false : true,\n\n          bucketName: UrlName.globally(this, 'MyBucket'),\n          // acme-corp-my-cool-project-feature-foo-bar-my-bucket\n        });\n\n        new ssm.StringParameter(this, 'Parameter', {\n          stringValue: 'Foo',\n          tier: ssm.ParameterTier.ADVANCED,\n          parameterName: PathName.withProject(this, 'MyNamespace/MyParameter'),\n          // /MyCoolProject/Staging/MyNamespace/MyParameter\n        });\n      }\n    }\n    ```\n\n4. Define a new _environmental_ which `extends EnvironmentWrapper` and initialize all your environmental `SmartStack` stacks within:\n\n    ```ts\n    // lib/environment.ts\n    import { Construct } from 'constructs';\n    import { EnvironmentWrapper } from '@alma-cdk/project';\n    import { MyStack } from './my-stack';\n\n    export class Environment extends EnvironmentWrapper {\n      constructor(scope: Construct) {\n        super(scope);\n        new MyStack(this, 'MyStack', { description: 'This is required' });\n      }\n    }\n    ```\n\n    Resulting Stack properties (given `environment=staging`):\n\n    |        Property         |                    Example value                     |\n    | :---------------------- | :--------------------------------------------------- |\n    | `stackName`             | `\"MyCoolProject-Environment-Staging-MyExampleStack\"` |\n    | `terminationProtection` | `true`                                               |\n    | `env.account`           | `\"111111111111\"`                                     |\n    | `env.region`            | `\"eu-west-1\"`                                        |\n\n    Resulting Tags for the Stack and its resources (given `environment=staging`):\n\n    |        Property         |           Example value           |\n    | :---------------------- | :-------------------------------- |\n    | `Account`               | `dev`                             |\n    | `Environment`           | `staging`                         |\n    | `Project`               | `my-cool-project`                 |\n    | `Author`                | `Mad Scientists`                  |\n    | `Organization`          | `Acme Corp`                       |\n    | `Contact`               | `mad.scientists@acme.example.com` |\n\n5. Finally initialize the environment with the `Project` scope:\n\n    ```ts\n    // bin/app.ts\n    import { Project, Accounts } from '@alma-cdk/project';\n    import { Environment } from '../lib/environment';\n\n    const project = new Project({/* removed for brevity, see step 1 */})\n\n    new Environment(project);\n    ```\n\n<br/>\n\n\n## Documentation\n\nSee detailed documentation for specific classes & methods at [constructs.dev](http://constructs.dev/packages/@alma-cdk/project).\n\nGenerally speaking you would be most interested in the following:\n- Project\n- AccountStrategy\n- SmartStack\n- AccountWrapper & EnvironmentWrapper\n- AccountContext (AC)\n- EnvironmentContext (EC)\n- Name / UrlName / PathName\n\n## Migration\n\n### v0 to v1\n\n#### Tagging behavior\n\nDue to a bug in `v0`, the `Contact` and `Organization` tags were NOT applied as they should have. This means that by default, upgrading from v0→v1 introduces CloudFormation diff. Basically adding the `Contact` and `Organization` tags to all resources. This should be safe operation, but we allow disabling it via a feature flag (note that `Contact` and `Organization` tags will most likely be enforced in future `v2`).\n\n```diff\n// cdk.json\n{\n  \"context\": {\n    // existing context keys\n+   \"@alma-cdk/project:compatibilityV0Tags\": true\n  },\n}\n```\n"
+    "markdown": "<div align=\"center\">\n  <h1>\n\t<img width=\"512\" src=\"assets/alma-cdk-project.svg\" alt=\"Alma CDK Project\" />\n  <br/>\n  <br/>\n  </h1>\n\n  ![Stability: Stable](https://img.shields.io/badge/stability-stable-%234BCA2A)\n  ![Versioning: SemVer 2.0.0](https://img.shields.io/badge/versioning-semver_2.0.0-blue)\n  [![release](https://github.com/alma-cdk/project/actions/workflows/release.yml/badge.svg)](https://github.com/alma-cdk/project/actions/workflows/release.yml)\n  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=alma-cdk_project&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=alma-cdk_project)\n  [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=alma-cdk_project&metric=coverage)](https://sonarcloud.io/summary/new_code?id=alma-cdk_project)\n  <hr/>\n</div>\n\n> [!Tip]\n> Migrating from `v0` to `v1`? See [Migration Guide](/docs/MIGRATION-GUIDE-0-to-1.md).\n\n<br/>\n\nOpinionated CDK “framework” with constructs & utilities for:\n- deploying multiple environments to multiple accounts (with many-to-many relationship)\n- managing account configuration through standardized props (no more random config files)\n- querying account and/or environment specific information within your CDK code\n- enabling dynamic & short-lived “feature-environments”\n- enabling well-defined tagging\n- providing structure & common conventions to CDK projects\n- choosing the target account & environment by passing in runtime context:\n\n  ```sh\n  npx cdk deploy -c account=dev -c environment=feature/abc-123\n  ```\n  ... which means you don't need to define all the possible environments ahead of time!\n\n\n\n## Account Strategies\n\nDepending on the use case, you may choose a configuration between 1-3 AWS accounts with the following environments:\n\n\n1. **Shared account (`shared`)**:\n\n    ![default-multi](assets/accounts-1x.svg)\n    <br/>\n\n2. **Multi-account (`dev`+`prod`)**_– RECOMMENDED_:\n\n    ![default-multi](assets/accounts-2x.svg)\n    <br/>\n\n<br/>\n</details>\n\n3. **Multi-account (`dev`+`preprod`+`prod`)**:\n\n    ![default-multi](assets/accounts-3x.svg)\n    <br/>\n\n<br/>\n\n## Getting Started\n\nSteps required to define a _environmental_ project resources; At first, it might seem complex but once you get into the habbit of defining your projects this way it starts to make sense:\n\n1. Choose your [Account Strategy](#account-strategies)\n\n2. Initialize a new `Project` instead of `cdk.App`:\n\n    ```ts\n    // bin/app.ts\n    import { Project, AccountStrategy } from '@alma-cdk/project';\n\n    const project = new Project({\n      // Basic info, you could also read these from package.json if you want\n      name: 'my-cool-project',\n      author: {\n        organization: 'Acme Corp',\n        name: 'Mad Scientists',\n        email: 'mad.scientists@acme.example.com',\n      },\n\n      // If not set, defaults to one of: $CDK_DEFAULT_REGION, $AWS_REGION or us-east-1\n      defaultRegion: 'eu-west-1',\n\n      // Configures the project to use 2 AWS accounts (recommended)\n      accounts: AccountStrategy.two({\n        dev: {\n          id: '111111111111',\n          config: {\n            // whatever you want here as [string]: any\n            baseDomain: 'example.net',\n          },\n        },\n        prod: {\n          id: '222222222222',\n          config: {\n            // whatever you want here as [string]: any\n            baseDomain: 'example.com',\n          },\n        },\n      }),\n    })\n    ```\n\n3. Define a stack which `extends SmartStack` with resources:\n    ```ts\n    // lib/my-stack.ts\n    import { Construct } from 'constructs';\n    import { StackProps, RemovalPolicy } from 'aws-cdk-lib';\n    import { SmartStack, Name, UrlName, PathName, EC } from '@alma-cdk/project';\n\n    export class MyStack extends SmartStack {\n      constructor(scope: Construct, id: string, props: StackProps) {\n        super(scope, id, props);\n\n        new dynamodb.Table(this, 'Table', {\n          removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,\n\n          tableName: Name.it(this, 'MyTable'),\n          partitionKey: {\n            type: dynamodb.AttributeType.STRING,\n            name: 'pk',\n          },\n          // StagingMyTable\n        });\n\n        new events.EventBus(this, 'EventBus', {\n          eventBusName: Name.withProject(this, 'MyEventBus'),\n          // MyCoolProjectStagingMyEventBus\n        });\n\n        new s3.Bucket(this, 'Bucket', {\n\n          removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,\n          autoDeleteObjects: EC.isStable(this) ? false : true,\n\n          bucketName: UrlName.globally(this, 'MyBucket'),\n          // acme-corp-my-cool-project-feature-foo-bar-my-bucket\n        });\n\n        new ssm.StringParameter(this, 'Parameter', {\n          stringValue: 'Foo',\n          tier: ssm.ParameterTier.ADVANCED,\n          parameterName: PathName.withProject(this, 'MyNamespace/MyParameter'),\n          // /MyCoolProject/Staging/MyNamespace/MyParameter\n        });\n      }\n    }\n    ```\n\n4. Define a new _environmental_ which `extends EnvironmentWrapper` and initialize all your environmental `SmartStack` stacks within:\n\n    ```ts\n    // lib/environment.ts\n    import { Construct } from 'constructs';\n    import { EnvironmentWrapper } from '@alma-cdk/project';\n    import { MyStack } from './my-stack';\n\n    export class Environment extends EnvironmentWrapper {\n      constructor(scope: Construct) {\n        super(scope);\n        new MyStack(this, 'MyStack', { description: 'This is required' });\n      }\n    }\n    ```\n\n    Resulting Stack properties (given `environment=staging`):\n\n    |        Property         |                    Example value                     |\n    | :---------------------- | :--------------------------------------------------- |\n    | `stackName`             | `\"MyCoolProject-Environment-Staging-MyExampleStack\"` |\n    | `terminationProtection` | `true`                                               |\n    | `env.account`           | `\"111111111111\"`                                     |\n    | `env.region`            | `\"eu-west-1\"`                                        |\n\n    Resulting Tags for the Stack and its resources (given `environment=staging`):\n\n    |        Property         |           Example value           |\n    | :---------------------- | :-------------------------------- |\n    | `Account`               | `dev`                             |\n    | `Environment`           | `staging`                         |\n    | `Project`               | `my-cool-project`                 |\n    | `Author`                | `Mad Scientists`                  |\n    | `Organization`          | `Acme Corp`                       |\n    | `Contact`               | `mad.scientists@acme.example.com` |\n\n5. Finally initialize the environment with the `Project` scope:\n\n    ```ts\n    // bin/app.ts\n    import { Project, Accounts } from '@alma-cdk/project';\n    import { Environment } from '../lib/environment';\n\n    const project = new Project({/* removed for brevity, see step 1 */})\n\n    new Environment(project);\n    ```\n\n<br/>\n\n\n## Documentation\n\nSee detailed documentation for specific classes & methods at [constructs.dev](http://constructs.dev/packages/@alma-cdk/project).\n\nGenerally speaking you would be most interested in the following:\n- Project\n- AccountStrategy\n- SmartStack\n- AccountWrapper & EnvironmentWrapper\n- AccountContext (AC)\n- EnvironmentContext (EC)\n- Name / UrlName / PathName\n\nMigrating from `v0` to `v1`? See [Migration Guide](/docs/MIGRATION-GUIDE-0-to-1.md).\n\n<br/>\n"
   },
   "repository": {
     "type": "git",
@@ -6320,6 +6320,6 @@
       "symbolId": "src/name/name-url:UrlName"
     }
   },
-  "version": "1.0.1",
-  "fingerprint": "GlZNKsH4jo3fr9hfyXIHjroY7BBowPUTLcVJI+duxhM="
+  "version": "1.0.3",
+  "fingerprint": "M0w9l9SlJ4ormrurMadPumFFTwqtIq2SnP9tWnb//LQ="
 }

package/README.md

@@ -1,38 +1,37 @@
 <div align="center">
-	<br/>
-	<br/>
   <h1>
-	<img width="300" src="assets/alma-cdk-project.svg" alt="Alma CDK Project" />
+	<img width="512" src="assets/alma-cdk-project.svg" alt="Alma CDK Project" />
   <br/>
   <br/>
   </h1>
 
-  ![NPM License](https://img.shields.io/npm/l/%40alma-cdk%2Fproject)
+  ![Stability: Stable](https://img.shields.io/badge/stability-stable-%234BCA2A)
+  ![Versioning: SemVer 2.0.0](https://img.shields.io/badge/versioning-semver_2.0.0-blue)
   [![release](https://github.com/alma-cdk/project/actions/workflows/release.yml/badge.svg)](https://github.com/alma-cdk/project/actions/workflows/release.yml)
+  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=alma-cdk_project&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=alma-cdk_project)
+  [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=alma-cdk_project&metric=coverage)](https://sonarcloud.io/summary/new_code?id=alma-cdk_project)
+  <hr/>
+</div>
 
-  ```sh
-  npm i -D @alma-cdk/project
-  ```
+> [!Tip]
+> Migrating from `v0` to `v1`? See [Migration Guide](/docs/MIGRATION-GUIDE-0-to-1.md).
 
-  <div align="left">
+<br/>
 
-  Opinionated CDK “framework” with constructs & utilities for:
-  - deploying multiple environments to multiple accounts (with many-to-many relationship)
-  - managing account configuration through standardized props (no more random config files)
-  - querying account and/or environment specific information within your CDK code
-  - enabling dynamic & short-lived “feature-environments”
-  - enabling well-defined tagging
-  - providing structure & common conventions to CDK projects
-  - choosing the target account & environment by passing in runtime context:
+Opinionated CDK “framework” with constructs & utilities for:
+- deploying multiple environments to multiple accounts (with many-to-many relationship)
+- managing account configuration through standardized props (no more random config files)
+- querying account and/or environment specific information within your CDK code
+- enabling dynamic & short-lived “feature-environments”
+- enabling well-defined tagging
+- providing structure & common conventions to CDK projects
+- choosing the target account & environment by passing in runtime context:
 
-    ```sh
-    npx cdk deploy -c account=dev -c environment=feature/abc-123
-    ```
-    ... which means you don't need to define all the possibile environments ahead of time!
+  ```sh
+  npx cdk deploy -c account=dev -c environment=feature/abc-123
+  ```
+  ... which means you don't need to define all the possible environments ahead of time!
 
-  </div>
-  <br/>
-</div>
 
 
 ## Account Strategies
@@ -214,20 +213,6 @@ Generally speaking you would be most interested in the following:
 - EnvironmentContext (EC)
 - Name / UrlName / PathName
 
-## Migration
-
-### v0 to v1
+Migrating from `v0` to `v1`? See [Migration Guide](/docs/MIGRATION-GUIDE-0-to-1.md).
 
-#### Tagging behavior
-
-Due to a bug in `v0`, the `Contact` and `Organization` tags were NOT applied as they should have. This means that by default, upgrading from v0→v1 introduces CloudFormation diff. Basically adding the `Contact` and `Organization` tags to all resources. This should be safe operation, but we allow disabling it via a feature flag (note that `Contact` and `Organization` tags will most likely be enforced in future `v2`).
-
-```diff
-// cdk.json
-{
-  "context": {
-    // existing context keys
-+   "@alma-cdk/project:compatibilityV0Tags": true
-  },
-}
-```
+<br/>