projen-pipelines 0.2.8 → 0.2.10

package/llm.md

@@ -0,0 +1,214 @@
+# Projen Pipelines - LLM Context
+
+This document provides comprehensive information about the projen-pipelines library to assist LLMs in generating code and providing accurate guidance.
+
+## Overview
+
+Projen Pipelines is an open-source project that automates CI/CD pipeline generation using Projen (a project configuration tool created by the inventor of AWS CDK). It provides high-level abstractions for defining continuous delivery pipelines with a focus on AWS CDK applications.
+
+The library supports multiple CI/CD platforms (currently GitHub Actions, GitLab CI, and bash scripts) and allows users to easily switch between them without rewriting pipeline configurations.
+
+## Key Features
+
+- **Automated pipeline code generation**: Generate CI/CD configuration files without manual writing
+- **Multi-platform support**: Deploy to GitHub Actions, GitLab CI, or bash scripts
+- **Baked-in proven defaults**: Optimized pipeline configurations
+- **Compliance-as-code integration**: Integrate compliance requirements directly into pipelines
+- **Platform migration support**: Switch CI/CD platforms with minimal code changes
+- **Complex deployment scenarios**: Handle multi-stage, multi-account deployments
+- **AWS infrastructure management**: Streamlined deployment to AWS environments
+
+## Core Architecture
+
+Projen-pipelines is built on these architectural components:
+
+1. **Pipeline Engines**: Abstract interfaces with concrete implementations for each CI/CD platform
+2. **Pipeline Steps**: Modular, composable actions that make up pipeline workflows
+3. **CDK Integration**: Specialized components for AWS CDK applications
+4. **Configuration Generation**: Automated creation of platform-specific configuration files
+
+## Pipeline Steps
+
+Steps are the fundamental building blocks. Key step types include:
+
+- `PipelineStep` (abstract base class)
+- `SimpleCommandStep` (execute shell commands)
+- `ProjenScriptStep` (run projen scripts)
+- `StepSequence` (combine multiple steps)
+- `AwsAssumeRoleStep` (assume AWS IAM roles)
+- Various artifact management steps
+
+## CDK Pipeline Integration
+
+For AWS CDK applications, the library provides:
+
+- `CDKPipeline` (abstract base class)
+- Platform-specific implementations (e.g., `GithubCDKPipeline`)
+- Support for multi-stage deployments (dev, prod, personal)
+- Asset publishing and versioning
+- Automated CloudFormation deployment
+
+## Usage Example
+
+```typescript
+import { awscdk } from 'projen';
+import { GithubCDKPipeline } from 'projen-pipelines';
+
+// Define your AWS CDK TypeScript App
+const app = new awscdk.AwsCdkTypeScriptApp({
+  cdkVersion: '2.150.0',
+  name: 'my-awesome-app',
+  defaultReleaseBranch: 'main',
+  devDeps: [
+    'projen-pipelines',
+  ],
+});
+
+// Create the pipeline
+new GithubCDKPipeline(app, {
+  stackPrefix: 'MyApp',
+  iamRoleArns: {
+    default: 'arn:aws:iam::123456789012:role/GithubDeploymentRole',
+  },
+  useGithubEnvironments: true,
+  stages: [
+    {
+      name: 'dev',
+      env: { account: '123456789013', region: 'eu-central-1' },
+    }, {
+      name: 'prod',
+      manualApproval: true,
+      env: { account: '123456789014', region: 'eu-central-1' },
+    }],
+});
+```
+
+After running `npx projen`, a specialized `app.ts` file is created for your CDK application. 
+Use it in your main.ts:
+
+```typescript
+import { PipelineApp } from './app';
+import { BackendStack } from './stack';
+
+const app = new PipelineApp({
+  provideDevStack: (scope, id, props) => {
+    return new BackendStack(scope, id, {
+      ...props,
+      apiHostname: 'api-dev',
+      myConfigSetting: 'value-for-dev',
+    });
+  },
+  provideProdStack: (scope, id, props) => {
+    return new BackendStack(scope, id, {
+      ...props,
+      apiHostname: 'api',
+      myConfigSetting: 'value-for-prod',
+    });
+  },
+  providePersonalStack: (scope, id, props) => {
+    return new BackendStack(scope, id, {
+      ...props,
+      apiHostname: `api-${props.stageName}`,
+      myConfigSetting: 'value-for-personal-stage',
+    });
+  },
+});
+
+app.synth();
+```
+
+## Pipeline Configuration Options
+
+When creating a CDK pipeline, these are key configuration options:
+
+| Option | Description |
+|--------|-------------|
+| `stackPrefix` | Prefix for CloudFormation stack names |
+| `iamRoleArns` | IAM roles for AWS access during deployment |
+| `pkgNamespace` | Namespace for published packages |
+| `stages` | Array of deployment stages with environment settings |
+| `useGithubPackagesForAssembly` | Use GitHub Packages for assembly storage |
+
+## Deployment Stages
+
+Each stage can have these properties:
+
+| Property | Description |
+|----------|-------------|
+| `name` | Stage name (e.g., 'dev', 'prod') |
+| `env` | AWS environment (account ID and region) |
+| `manualApproval` | Require manual approval before deployment |
+
+## IAM Trust Configuration
+
+For multi-account deployments, trust relationships are needed between accounts:
+
+1. Bootstrap each account with CDK: 
+   ```bash
+   cdk bootstrap --trust <deployment_account_id> --cloudformation-execution-policies "arn:aws:iam::aws:policy/AdministratorAccess"
+   ```
+
+2. Create an IAM role in the deployment account that can assume roles in target accounts:
+   ```json
+   {
+       "Version": "2012-10-17",
+       "Statement": [
+           {
+               "Effect": "Allow",
+               "Action": "sts:AssumeRole",
+               "Resource": [
+                   "arn:aws:iam::123456789013:role/cdk-*-123456789013-*",
+                   "arn:aws:iam::123456789014:role/cdk-*-123456789014-*"
+               ]
+           }
+       ]
+   }
+   ```
+
+3. Configure OIDC trust for GitHub Actions (see [GitHub documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services))
+
+## Generated Tasks
+
+The CDK pipeline adds these tasks to your projen project:
+
+| Task | Description |
+|------|-------------|
+| `deploy:personal` | Deploy personal development environment |
+| `watch:personal` | Deploy personal environment in watch mode |
+| `diff:personal` | Compare personal environment with code |
+| `destroy:personal` | Remove personal environment |
+| `deploy:feature` | Deploy feature branch environment |
+| `diff:feature` | Compare feature environment with code |
+| `destroy:feature` | Remove feature environment |
+| `deploy:<stageName>` | Deploy a specific stage |
+| `diff:<stageName>` | Compare stage with code |
+| `publish:assets` | Publish CDK assets to all accounts |
+| `bump` | Bump version based on git tags |
+| `release:push-assembly` | Publish cloud assembly to registry |
+
+## Best Practices
+
+1. **IAM Role Setup**: Create minimal permission IAM roles for deployment
+2. **Account Bootstrapping**: Bootstrap all accounts with appropriate trust relationships
+3. **Testing Locally**: Use the `deploy:personal` task for testing changes locally
+4. **Environment Variables**: For GitHub token issues, run `GITHUB_TOKEN= npx projen`
+5. **Security**: Never use `AdministratorAccess` in production; use custom IAM policies
+
+## Current Status and Limitations
+
+Projen-Pipelines is currently in version 0.x, awaiting Projen's 1.0 release. Despite being pre-1.0, it's being used in production environments.
+
+## Extension Points
+
+The library is designed for extension via:
+
+1. Creating custom pipeline steps
+2. Implementing new engine adapters
+3. Adding support for new application types
+4. Contributing new deployment patterns
+
+## For More Information
+
+- GitHub Repository: https://github.com/open-constructs/projen-pipelines
+- API Documentation: See the API.md file
+- Examples: See the README.md for usage examples

package/node_modules/semver/bin/semver.js

@@ -3,6 +3,8 @@
 // Exits successfully and prints matching version(s) if
 // any supplied version is valid and passes all tests.
 
+'use strict'
+
 const argv = process.argv.slice(2)
 
 let versions = []

package/node_modules/semver/classes/comparator.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const ANY = Symbol('SemVer ANY')
 // hoisted class for cyclic dependency
 class Comparator {

package/node_modules/semver/classes/index.js

@@ -1,3 +1,5 @@
+'use strict'
+
 module.exports = {
   SemVer: require('./semver.js'),
   Range: require('./range.js'),

package/node_modules/semver/classes/range.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SPACE_CHARACTERS = /\s+/g
 
 // hoisted class for cyclic dependency

package/node_modules/semver/classes/semver.js

@@ -1,6 +1,8 @@
+'use strict'
+
 const debug = require('../internal/debug')
 const { MAX_LENGTH, MAX_SAFE_INTEGER } = require('../internal/constants')
-const { safeRe: re, safeSrc: src, t } = require('../internal/re')
+const { safeRe: re, t } = require('../internal/re')
 
 const parseOptions = require('../internal/parse-options')
 const { compareIdentifiers } = require('../internal/identifiers')
@@ -182,8 +184,7 @@ class SemVer {
       }
       // Avoid an invalid semver results
       if (identifier) {
-        const r = new RegExp(`^${this.options.loose ? src[t.PRERELEASELOOSE] : src[t.PRERELEASE]}$`)
-        const match = `-${identifier}`.match(r)
+        const match = `-${identifier}`.match(this.options.loose ? re[t.PRERELEASELOOSE] : re[t.PRERELEASE])
         if (!match || match[1] !== identifier) {
           throw new Error(`invalid identifier: ${identifier}`)
         }

package/node_modules/semver/functions/clean.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const parse = require('./parse')
 const clean = (version, options) => {
   const s = parse(version.trim().replace(/^[=v]+/, ''), options)

package/node_modules/semver/functions/cmp.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const eq = require('./eq')
 const neq = require('./neq')
 const gt = require('./gt')

package/node_modules/semver/functions/coerce.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const parse = require('./parse')
 const { safeRe: re, t } = require('../internal/re')

package/node_modules/semver/functions/compare-build.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const compareBuild = (a, b, loose) => {
   const versionA = new SemVer(a, loose)

package/node_modules/semver/functions/compare-loose.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const compareLoose = (a, b) => compare(a, b, true)
 module.exports = compareLoose

package/node_modules/semver/functions/compare.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const compare = (a, b, loose) =>
   new SemVer(a, loose).compare(new SemVer(b, loose))

package/node_modules/semver/functions/diff.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const parse = require('./parse.js')
 
 const diff = (version1, version2) => {

package/node_modules/semver/functions/eq.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const eq = (a, b, loose) => compare(a, b, loose) === 0
 module.exports = eq

package/node_modules/semver/functions/gt.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const gt = (a, b, loose) => compare(a, b, loose) > 0
 module.exports = gt

package/node_modules/semver/functions/gte.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const gte = (a, b, loose) => compare(a, b, loose) >= 0
 module.exports = gte

package/node_modules/semver/functions/inc.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 
 const inc = (version, release, options, identifier, identifierBase) => {

package/node_modules/semver/functions/lt.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const lt = (a, b, loose) => compare(a, b, loose) < 0
 module.exports = lt

package/node_modules/semver/functions/lte.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const lte = (a, b, loose) => compare(a, b, loose) <= 0
 module.exports = lte

package/node_modules/semver/functions/major.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const major = (a, loose) => new SemVer(a, loose).major
 module.exports = major

package/node_modules/semver/functions/minor.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const minor = (a, loose) => new SemVer(a, loose).minor
 module.exports = minor

package/node_modules/semver/functions/neq.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const neq = (a, b, loose) => compare(a, b, loose) !== 0
 module.exports = neq

package/node_modules/semver/functions/parse.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const parse = (version, options, throwErrors = false) => {
   if (version instanceof SemVer) {

package/node_modules/semver/functions/patch.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const patch = (a, loose) => new SemVer(a, loose).patch
 module.exports = patch

package/node_modules/semver/functions/prerelease.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const parse = require('./parse')
 const prerelease = (version, options) => {
   const parsed = parse(version, options)

package/node_modules/semver/functions/rcompare.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compare = require('./compare')
 const rcompare = (a, b, loose) => compare(b, a, loose)
 module.exports = rcompare

package/node_modules/semver/functions/rsort.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compareBuild = require('./compare-build')
 const rsort = (list, loose) => list.sort((a, b) => compareBuild(b, a, loose))
 module.exports = rsort

package/node_modules/semver/functions/satisfies.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const Range = require('../classes/range')
 const satisfies = (version, range, options) => {
   try {

package/node_modules/semver/functions/sort.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const compareBuild = require('./compare-build')
 const sort = (list, loose) => list.sort((a, b) => compareBuild(a, b, loose))
 module.exports = sort

package/node_modules/semver/functions/valid.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const parse = require('./parse')
 const valid = (version, options) => {
   const v = parse(version, options)

package/node_modules/semver/index.js

@@ -1,3 +1,5 @@
+'use strict'
+
 // just pre-load all the stuff that index.js lazily exports
 const internalRe = require('./internal/re')
 const constants = require('./internal/constants')

package/node_modules/semver/internal/constants.js

@@ -1,3 +1,5 @@
+'use strict'
+
 // Note: this is the semver.org version of the spec that it implements
 // Not necessarily the package version of this code.
 const SEMVER_SPEC_VERSION = '2.0.0'

package/node_modules/semver/internal/debug.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const debug = (
   typeof process === 'object' &&
   process.env &&

package/node_modules/semver/internal/identifiers.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const numeric = /^[0-9]+$/
 const compareIdentifiers = (a, b) => {
   const anum = numeric.test(a)

package/node_modules/semver/internal/lrucache.js

@@ -1,3 +1,5 @@
+'use strict'
+
 class LRUCache {
   constructor () {
     this.max = 1000

package/node_modules/semver/internal/parse-options.js

@@ -1,3 +1,5 @@
+'use strict'
+
 // parse out just the options we care about
 const looseOption = Object.freeze({ loose: true })
 const emptyOpts = Object.freeze({ })

package/node_modules/semver/internal/re.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const {
   MAX_SAFE_COMPONENT_LENGTH,
   MAX_SAFE_BUILD_LENGTH,
@@ -76,12 +78,14 @@ createToken('MAINVERSIONLOOSE', `(${src[t.NUMERICIDENTIFIERLOOSE]})\\.` +
 
 // ## Pre-release Version Identifier
 // A numeric identifier, or a non-numeric identifier.
+// Non-numberic identifiers include numberic identifiers but can be longer.
+// Therefore non-numberic identifiers must go first.
 
-createToken('PRERELEASEIDENTIFIER', `(?:${src[t.NUMERICIDENTIFIER]
-}|${src[t.NONNUMERICIDENTIFIER]})`)
+createToken('PRERELEASEIDENTIFIER', `(?:${src[t.NONNUMERICIDENTIFIER]
+}|${src[t.NUMERICIDENTIFIER]})`)
 
-createToken('PRERELEASEIDENTIFIERLOOSE', `(?:${src[t.NUMERICIDENTIFIERLOOSE]
-}|${src[t.NONNUMERICIDENTIFIER]})`)
+createToken('PRERELEASEIDENTIFIERLOOSE', `(?:${src[t.NONNUMERICIDENTIFIER]
+}|${src[t.NUMERICIDENTIFIERLOOSE]})`)
 
 // ## Pre-release Version
 // Hyphen, followed by one or more dot-separated pre-release version

package/node_modules/semver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semver",
-  "version": "7.7.1",
+  "version": "7.7.2",
   "description": "The semantic version parser used by npm.",
   "main": "index.js",
   "scripts": {
@@ -15,7 +15,7 @@
   },
   "devDependencies": {
     "@npmcli/eslint-config": "^5.0.0",
-    "@npmcli/template-oss": "4.23.4",
+    "@npmcli/template-oss": "4.24.3",
     "benchmark": "^2.1.4",
     "tap": "^16.0.0"
   },
@@ -52,7 +52,7 @@
   "author": "GitHub Inc.",
   "templateOSS": {
     "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
-    "version": "4.23.4",
+    "version": "4.24.3",
     "engines": ">=10",
     "distPaths": [
       "classes/",

package/node_modules/semver/preload.js

@@ -1,2 +1,4 @@
+'use strict'
+
 // XXX remove in v8 or beyond
 module.exports = require('./index.js')

package/node_modules/semver/ranges/gtr.js

@@ -1,3 +1,5 @@
+'use strict'
+
 // Determine if version is greater than all the versions possible in the range.
 const outside = require('./outside')
 const gtr = (version, range, options) => outside(version, range, '>', options)

package/node_modules/semver/ranges/intersects.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const Range = require('../classes/range')
 const intersects = (r1, r2, options) => {
   r1 = new Range(r1, options)

package/node_modules/semver/ranges/ltr.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const outside = require('./outside')
 // Determine if version is less than all the versions possible in the range
 const ltr = (version, range, options) => outside(version, range, '<', options)

package/node_modules/semver/ranges/max-satisfying.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const Range = require('../classes/range')
 

package/node_modules/semver/ranges/min-satisfying.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const Range = require('../classes/range')
 const minSatisfying = (versions, range, options) => {

package/node_modules/semver/ranges/min-version.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const Range = require('../classes/range')
 const gt = require('../functions/gt')

package/node_modules/semver/ranges/outside.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const SemVer = require('../classes/semver')
 const Comparator = require('../classes/comparator')
 const { ANY } = Comparator

package/node_modules/semver/ranges/simplify.js

@@ -1,3 +1,5 @@
+'use strict'
+
 // given a set of versions and a range, create a "simplified" range
 // that includes the same versions that the original range does
 // If the original range is shorter than the simplified one, return that.

package/node_modules/semver/ranges/subset.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const Range = require('../classes/range.js')
 const Comparator = require('../classes/comparator.js')
 const { ANY } = Comparator

package/node_modules/semver/ranges/to-comparators.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const Range = require('../classes/range')
 
 // Mostly just for testing and legacy API reasons

package/node_modules/semver/ranges/valid.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const Range = require('../classes/range')
 const validRange = (range, options) => {
   try {

package/package.json

@@ -48,18 +48,18 @@
     "commit-and-tag-version": "^12",
     "constructs": "10.4.2",
     "eslint": "^9",
-    "eslint-import-resolver-typescript": "^3.10.0",
+    "eslint-import-resolver-typescript": "^3.10.1",
     "eslint-plugin-import": "^2.31.0",
     "fs-extra": "^11.3.0",
     "jest": "^29.7.0",
     "jest-junit": "^16",
     "jsii": "~5.8",
-    "jsii-diff": "^1.111.0",
+    "jsii-diff": "^1.112.0",
     "jsii-docgen": "^10.5.0",
-    "jsii-pacmak": "^1.106.0",
+    "jsii-pacmak": "^1.112.0",
     "jsii-rosetta": "~5.8",
     "projen": "0.91.20",
-    "ts-jest": "^29.3.1",
+    "ts-jest": "^29.3.4",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
   },
@@ -83,7 +83,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.8",
+  "version": "0.2.10",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [