@jaypie/mcp 0.3.2 → 0.4.0

package/prompts/Jaypie_Init_CICD_with_GitHub_Actions.md

@@ -1,1186 +0,0 @@
----
-description: step-by-step guide to initialize GitHub Actions CI/CD for Jaypie projects
----
-
-# Initialize CI/CD with GitHub Actions
-
-This guide walks through setting up GitHub Actions CI/CD from scratch for a Jaypie project.
-
-## Workspace Naming Conventions
-
-| Directory | Purpose |
-|-----------|---------|
-| `packages/` | Default workspace for npm packages (preferred when only one namespace needed) |
-| `stacks/` | CDK-deployed infrastructure and sites (as opposed to npm-published) |
-| `workspaces/` | Generic workspace for other work |
-
-## Prerequisites
-
-- GitHub repository with Jaypie project structure
-- AWS account with OIDC provider configured for GitHub Actions
-- GitHub environments configured (development, sandbox, production)
-
-## Directory Structure
-
-Create the following structure:
-
-```
-.github/
-├── actions/
-│   ├── cdk-deploy/
-│   │   └── action.yml
-│   ├── configure-aws/
-│   │   └── action.yml
-│   ├── npm-install-build/
-│   │   └── action.yml
-│   ├── setup-environment/
-│   │   └── action.yml
-│   └── setup-node-and-cache/
-│       └── action.yml
-└── workflows/
-    ├── check-production.yml
-    ├── deploy-env-development.yml
-    ├── deploy-env-production.yml
-    ├── deploy-env-sandbox.yml
-    └── version.yml
-```
-
-## Step 1: Create Composite Actions
-
-Composite actions provide reusable workflow steps. Create each file in `.github/actions/`.
-
-### configure-aws/action.yml
-
-Configures AWS credentials using OIDC.
-
-```yaml
-name: Configure AWS Credentials
-description: Configure AWS credentials using OIDC for GitHub Actions
-
-inputs:
-  role-arn:
-    description: AWS IAM role ARN to assume
-    required: true
-  aws-region:
-    description: AWS region
-    required: false
-    default: us-east-1
-  role-session-name:
-    description: Name for the role session
-    required: false
-    default: DeployRoleForGitHubSession
-
-runs:
-  using: composite
-  steps:
-    - name: Configure AWS Credentials
-      uses: aws-actions/configure-aws-credentials@v4
-      with:
-        role-to-assume: ${{ inputs.role-arn }}
-        role-session-name: ${{ inputs.role-session-name }}
-        aws-region: ${{ inputs.aws-region }}
-```
-
-### setup-node-and-cache/action.yml
-
-Sets up Node.js with caching for dependencies.
-
-```yaml
-name: Setup Node.js and Cache Dependencies
-description: Checkout code, setup Node.js with npm cache, and configure dependency caching
-
-inputs:
-  node-version:
-    description: Node.js version to use
-    required: false
-    default: "24"
-
-outputs:
-  node-modules-cache-hit:
-    description: Whether node_modules cache was hit
-    value: ${{ steps.cache-node-modules.outputs.cache-hit }}
-
-runs:
-  using: composite
-  steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Setup Node.js ${{ inputs.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        cache: npm
-        node-version: ${{ inputs.node-version }}
-
-    - name: Cache node_modules
-      id: cache-node-modules
-      uses: actions/cache@v4
-      with:
-        path: |
-          node_modules
-          packages/*/node_modules
-          stacks/*/node_modules
-        key: ${{ runner.os }}-node-${{ inputs.node-version }}-modules-${{ hashFiles('**/package-lock.json') }}
-        restore-keys: |
-          ${{ runner.os }}-node-${{ inputs.node-version }}-modules-
-
-    - name: Cache Status
-      shell: bash
-      run: |
-        echo "Node modules cache: ${{ steps.cache-node-modules.outputs.cache-hit == 'true' && '✓ HIT' || '✗ MISS' }}"
-```
-
-### npm-install-build/action.yml
-
-Installs dependencies and builds the project.
-
-```yaml
-name: NPM Install and Build
-description: Install dependencies and build the project
-
-inputs:
-  use-ci:
-    description: Use npm ci instead of npm install (recommended for CI/CD)
-    required: false
-    default: "true"
-  build-command:
-    description: NPM script to run for building
-    required: false
-    default: build
-
-runs:
-  using: composite
-  steps:
-    - name: Install dependencies
-      shell: bash
-      run: |
-        if [ "${{ inputs.use-ci }}" = "true" ]; then
-          npm ci
-        else
-          npm install
-        fi
-
-    - name: Build project
-      shell: bash
-      run: npm run ${{ inputs.build-command }}
-```
-
-### setup-environment/action.yml
-
-Configures environment variables with sensible defaults. Customize the defaults for your project.
-
-```yaml
-name: Setup Environment Variables
-description: |
-  Configure environment variables with sensible defaults for Jaypie projects.
-
-  Variable Scoping (GitHub Settings):
-  - Organization: AWS_REGION, LOG_LEVEL, MODULE_LOG_LEVEL, PROJECT_SPONSOR
-  - Repository: AWS_HOSTED_ZONE, PROJECT_KEY, PROJECT_SERVICE
-  - Environment: AWS_ROLE_ARN, DATADOG_API_KEY_ARN, PROJECT_ENV, PROJECT_NONCE
-
-  Environment Secrets:
-  - By default, no secrets are required
-  - Dependencies add secrets (e.g., Auth0 adds AUTH0_CLIENT_SECRET)
-  - Secrets are passed to CDK via JaypieEnvSecret construct
-
-inputs:
-  # Organization-level variables
-  aws-region:
-    description: AWS region (org-level)
-    required: false
-  log-level:
-    description: Application log level (org-level)
-    required: false
-  module-log-level:
-    description: Module log level (org-level)
-    required: false
-  project-sponsor:
-    description: Project sponsor (org-level)
-    required: false
-  # Repository-level variables
-  aws-hosted-zone:
-    description: Route53 hosted zone (repo-level)
-    required: false
-  project-key:
-    description: Project key (repo-level)
-    required: false
-  project-service:
-    description: Project service name (repo-level)
-    required: false
-  # Environment-level variables
-  aws-role-arn:
-    description: AWS IAM role ARN (env-level)
-    required: false
-  datadog-api-key-arn:
-    description: Datadog API key ARN (env-level)
-    required: false
-  project-env:
-    description: Project environment (env-level)
-    required: false
-  project-nonce:
-    description: Project nonce (env-level)
-    required: false
-
-outputs:
-  aws-region:
-    description: Resolved AWS region
-    value: ${{ steps.set-env.outputs.aws-region }}
-  aws-role-arn:
-    description: Resolved AWS role ARN
-    value: ${{ steps.set-env.outputs.aws-role-arn }}
-  project-env:
-    description: Resolved project environment
-    value: ${{ steps.set-env.outputs.project-env }}
-
-runs:
-  using: composite
-  steps:
-    - name: Set environment variables
-      id: set-env
-      shell: bash
-      run: |
-        # Organization-level variables (with defaults)
-        AWS_REGION="${{ inputs.aws-region }}"
-        AWS_REGION="${AWS_REGION:-us-east-1}"
-
-        LOG_LEVEL="${{ inputs.log-level }}"
-        LOG_LEVEL="${LOG_LEVEL:-debug}"
-
-        MODULE_LOG_LEVEL="${{ inputs.module-log-level }}"
-        MODULE_LOG_LEVEL="${MODULE_LOG_LEVEL:-warn}"
-
-        PROJECT_SPONSOR="${{ inputs.project-sponsor }}"
-        PROJECT_SPONSOR="${PROJECT_SPONSOR:-myorg}"
-
-        # Repository-level variables (with defaults)
-        HOSTED_ZONE="${{ inputs.aws-hosted-zone }}"
-        HOSTED_ZONE="${HOSTED_ZONE:-example.com}"
-
-        PROJECT_KEY="${{ inputs.project-key }}"
-        PROJECT_KEY="${PROJECT_KEY:-myapp}"
-
-        PROJECT_SERVICE="${{ inputs.project-service }}"
-        PROJECT_SERVICE="${PROJECT_SERVICE:-stacks}"
-
-        # Environment-level variables (with defaults)
-        AWS_ROLE_ARN="${{ inputs.aws-role-arn }}"
-
-        DATADOG_API_KEY_ARN="${{ inputs.datadog-api-key-arn }}"
-
-        PROJECT_ENV="${{ inputs.project-env }}"
-        PROJECT_ENV="${PROJECT_ENV:-sandbox}"
-
-        PROJECT_NONCE="${{ inputs.project-nonce }}"
-        PROJECT_NONCE="${PROJECT_NONCE:-$(echo $RANDOM | md5sum | head -c 8)}"
-
-        # Derived from package.json
-        PROJECT_VERSION=$(node -p "require('./package.json').version")
-
-        # Export all environment variables for CDK
-        echo "AWS_REGION=${AWS_REGION}" >> $GITHUB_ENV
-        echo "AWS_ROLE_ARN=${AWS_ROLE_ARN}" >> $GITHUB_ENV
-        echo "CDK_DEFAULT_ACCOUNT=${{ github.repository_owner }}" >> $GITHUB_ENV
-        echo "CDK_DEFAULT_REGION=${AWS_REGION}" >> $GITHUB_ENV
-        echo "CDK_ENV_DATADOG_API_KEY_ARN=${DATADOG_API_KEY_ARN}" >> $GITHUB_ENV
-        echo "CDK_ENV_HOSTED_ZONE=${HOSTED_ZONE}" >> $GITHUB_ENV
-        echo "CDK_ENV_REPO=${{ github.repository }}" >> $GITHUB_ENV
-        echo "LOG_LEVEL=${LOG_LEVEL}" >> $GITHUB_ENV
-        echo "MODULE_LOG_LEVEL=${MODULE_LOG_LEVEL}" >> $GITHUB_ENV
-        echo "PROJECT_COMMIT=${{ github.sha }}" >> $GITHUB_ENV
-        echo "PROJECT_ENV=${PROJECT_ENV}" >> $GITHUB_ENV
-        echo "PROJECT_KEY=${PROJECT_KEY}" >> $GITHUB_ENV
-        echo "PROJECT_NONCE=${PROJECT_NONCE}" >> $GITHUB_ENV
-        echo "PROJECT_SERVICE=${PROJECT_SERVICE}" >> $GITHUB_ENV
-        echo "PROJECT_SPONSOR=${PROJECT_SPONSOR}" >> $GITHUB_ENV
-        echo "PROJECT_VERSION=${PROJECT_VERSION}" >> $GITHUB_ENV
-
-        # Set outputs for subsequent steps
-        echo "aws-region=${AWS_REGION}" >> $GITHUB_OUTPUT
-        echo "aws-role-arn=${AWS_ROLE_ARN}" >> $GITHUB_OUTPUT
-        echo "project-env=${PROJECT_ENV}" >> $GITHUB_OUTPUT
-```
-
-### cdk-deploy/action.yml
-
-Builds and deploys CDK stack with caching.
-
-```yaml
-name: CDK Build and Deploy
-description: Build and deploy AWS CDK stack with caching
-
-inputs:
-  stack-name:
-    description: CDK stack name to deploy
-    required: true
-  cdk-package-path:
-    description: Path to CDK package
-    required: false
-    default: packages/cdk
-
-runs:
-  using: composite
-  steps:
-    - name: Cache CDK build
-      id: cache-cdk
-      uses: actions/cache@v4
-      with:
-        path: ${{ inputs.cdk-package-path }}/dist
-        key: ${{ runner.os }}-cdk-build-${{ hashFiles(format('{0}/package.json', inputs.cdk-package-path), format('{0}/package-lock.json', inputs.cdk-package-path), format('{0}/tsconfig.json', inputs.cdk-package-path), format('{0}/bin/**', inputs.cdk-package-path), format('{0}/lib/**', inputs.cdk-package-path)) }}
-        restore-keys: |
-          ${{ runner.os }}-cdk-build-
-
-    - name: CDK Cache Status
-      shell: bash
-      run: |
-        if [ "${{ steps.cache-cdk.outputs.cache-hit }}" == "true" ]; then
-          echo "✓ CDK build cache HIT - skipping rebuild"
-        else
-          echo "✗ CDK build cache MISS - will rebuild"
-        fi
-
-    - name: Build CDK
-      if: steps.cache-cdk.outputs.cache-hit != 'true'
-      shell: bash
-      run: npm --prefix ${{ inputs.cdk-package-path }} run build
-
-    - name: Deploy CDK Stack
-      shell: bash
-      run: npm --workspace ${{ inputs.cdk-package-path }} run cdk deploy -- ${{ inputs.stack-name }} --require-approval never
-```
-
-## Step 2: Create Workflow Files
-
-Create workflow files in `.github/workflows/`.
-
-### deploy-env-sandbox.yml
-
-Deploys to sandbox on feature branches. Lint and test run in parallel with deploy.
-
-```yaml
-name: Build to Sandbox
-
-on:
-  push:
-    branches:
-      - feat/*
-      - sandbox/*
-    tags:
-      - sandbox-*
-
-concurrency:
-  group: deploy-env-sandbox
-
-jobs:
-  deploy:
-    environment: sandbox
-    name: Deploy to AWS
-    permissions:
-      id-token: write
-      contents: read
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Environment
-        id: setup-env
-        uses: ./.github/actions/setup-environment
-        with:
-          aws-hosted-zone: ${{ vars.AWS_HOSTED_ZONE }}
-          aws-region: ${{ vars.AWS_REGION }}
-          aws-role-arn: ${{ vars.AWS_ROLE_ARN }}
-          datadog-api-key-arn: ${{ vars.DATADOG_API_KEY_ARN }}
-          log-level: ${{ vars.LOG_LEVEL }}
-          module-log-level: ${{ vars.MODULE_LOG_LEVEL }}
-          project-env: ${{ vars.PROJECT_ENV }}
-          project-key: ${{ vars.PROJECT_KEY }}
-          project-nonce: ${{ vars.PROJECT_NONCE }}
-          project-service: ${{ vars.PROJECT_SERVICE }}
-          project-sponsor: ${{ vars.PROJECT_SPONSOR }}
-
-      - name: Configure AWS Credentials
-        uses: ./.github/actions/configure-aws
-        with:
-          aws-region: ${{ steps.setup-env.outputs.aws-region }}
-          role-arn: ${{ steps.setup-env.outputs.aws-role-arn }}
-
-      - name: Setup Node.js and Cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install and Build
-        uses: ./.github/actions/npm-install-build
-
-      - name: Deploy CDK Stack
-        uses: ./.github/actions/cdk-deploy
-        with:
-          stack-name: AppStack
-
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Lint
-        run: npm run lint
-
-  test:
-    name: Unit Test
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [22, 24]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }} and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Tests
-        run: npm test
-```
-
-### deploy-env-development.yml
-
-Deploys to development from main branch. Requires lint and test to pass.
-
-```yaml
-name: Build to Development
-
-on:
-  push:
-    branches:
-      - main
-      - development/*
-    tags:
-      - development-*
-
-concurrency:
-  group: deploy-env-development
-
-jobs:
-  deploy:
-    environment: development
-    needs: [lint, test]
-    name: Deploy to AWS
-    permissions:
-      id-token: write
-      contents: read
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Environment
-        id: setup-env
-        uses: ./.github/actions/setup-environment
-        with:
-          aws-hosted-zone: ${{ vars.AWS_HOSTED_ZONE }}
-          aws-region: ${{ vars.AWS_REGION }}
-          aws-role-arn: ${{ vars.AWS_ROLE_ARN }}
-          datadog-api-key-arn: ${{ vars.DATADOG_API_KEY_ARN }}
-          log-level: ${{ vars.LOG_LEVEL }}
-          module-log-level: ${{ vars.MODULE_LOG_LEVEL }}
-          project-env: ${{ vars.PROJECT_ENV }}
-          project-key: ${{ vars.PROJECT_KEY }}
-          project-nonce: ${{ vars.PROJECT_NONCE }}
-          project-service: ${{ vars.PROJECT_SERVICE }}
-          project-sponsor: ${{ vars.PROJECT_SPONSOR }}
-
-      - name: Configure AWS Credentials
-        uses: ./.github/actions/configure-aws
-        with:
-          aws-region: ${{ steps.setup-env.outputs.aws-region }}
-          role-arn: ${{ steps.setup-env.outputs.aws-role-arn }}
-
-      - name: Setup Node.js and Cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install and Build
-        uses: ./.github/actions/npm-install-build
-
-      - name: Deploy CDK Stack
-        uses: ./.github/actions/cdk-deploy
-        with:
-          stack-name: AppStack
-
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Lint
-        run: npm run lint
-
-  test:
-    name: Unit Test
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [22, 24]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }} and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Tests
-        run: npm test
-```
-
-### deploy-env-production.yml
-
-Deploys to production from version tags. Requires lint and test to pass.
-
-```yaml
-name: Build to Production
-
-on:
-  push:
-    tags:
-      - 'production-*'
-      - 'v0.*'
-      - 'v1.*'
-
-concurrency:
-  group: deploy-env-production
-
-jobs:
-  deploy:
-    environment: production
-    needs: [lint, test]
-    if: |
-      always() &&
-      needs.lint.result == 'success' &&
-      needs.test.result == 'success'
-    name: Deploy to AWS
-    permissions:
-      id-token: write
-      contents: read
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Display deployment version
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          echo "::notice::Deploying version $VERSION to production"
-          echo "DEPLOY_VERSION=$VERSION" >> $GITHUB_ENV
-
-      - name: Setup Environment
-        id: setup-env
-        uses: ./.github/actions/setup-environment
-        with:
-          aws-hosted-zone: ${{ vars.AWS_HOSTED_ZONE }}
-          aws-region: ${{ vars.AWS_REGION }}
-          aws-role-arn: ${{ vars.AWS_ROLE_ARN }}
-          datadog-api-key-arn: ${{ vars.DATADOG_API_KEY_ARN }}
-          log-level: ${{ vars.LOG_LEVEL }}
-          module-log-level: ${{ vars.MODULE_LOG_LEVEL }}
-          project-env: ${{ vars.PROJECT_ENV }}
-          project-key: ${{ vars.PROJECT_KEY }}
-          project-nonce: ${{ vars.PROJECT_NONCE }}
-          project-service: ${{ vars.PROJECT_SERVICE }}
-          project-sponsor: ${{ vars.PROJECT_SPONSOR }}
-
-      - name: Configure AWS Credentials
-        uses: ./.github/actions/configure-aws
-        with:
-          aws-region: ${{ steps.setup-env.outputs.aws-region }}
-          role-arn: ${{ steps.setup-env.outputs.aws-role-arn }}
-
-      - name: Setup Node.js and Cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install and Build
-        uses: ./.github/actions/npm-install-build
-
-      - name: Deploy CDK Stack
-        uses: ./.github/actions/cdk-deploy
-        with:
-          stack-name: AppStack
-
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Lint
-        run: npm run lint
-
-  test:
-    name: Unit Test
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [22, 24]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }} and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Tests
-        run: npm test
-```
-
-### check-production.yml
-
-Runs checks on production branches without deploying.
-
-```yaml
-name: Check Production Build
-
-on:
-  push:
-    branches:
-      - production
-      - production-*
-      - production/*
-
-concurrency:
-  group: check-production
-
-jobs:
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: 24
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Lint
-        run: npm run lint
-
-  test:
-    name: Unit Test
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [22, 24]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }} and Cache
-        id: setup-cache
-        uses: ./.github/actions/setup-node-and-cache
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install dependencies
-        if: steps.setup-cache.outputs.node-modules-cache-hit != 'true'
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Tests
-        run: npm test
-```
-
-### version.yml
-
-Updates version across monorepo packages.
-
-```yaml
-name: Update Version
-
-on:
-  workflow_dispatch:
-    inputs:
-      version_type:
-        description: 'Version update type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-          - custom
-        default: patch
-      custom_version:
-        description: 'Custom version (e.g., 1.2.3) - only used if version_type is custom'
-        required: false
-        type: string
-  workflow_call:
-    inputs:
-      version_type:
-        description: 'Version update type'
-        required: false
-        type: string
-        default: patch
-      custom_version:
-        description: 'Custom version (e.g., 1.2.3) - only used if version_type is custom'
-        required: false
-        type: string
-    outputs:
-      new_version:
-        description: 'The new version number'
-        value: ${{ jobs.version.outputs.new_version }}
-
-jobs:
-  version:
-    name: Update and Sync Version
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    outputs:
-      new_version: ${{ steps.bump.outputs.new_version }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-
-      - name: Configure Git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Update root version
-        id: bump
-        run: |
-          VERSION_TYPE="${{ inputs.version_type }}"
-          CUSTOM_VERSION="${{ inputs.custom_version }}"
-
-          if [[ "$VERSION_TYPE" == "custom" ]]; then
-            if [[ -z "$CUSTOM_VERSION" ]]; then
-              echo "Error: custom_version is required when version_type is 'custom'"
-              exit 1
-            fi
-            npm version "$CUSTOM_VERSION" --no-git-tag-version --allow-same-version
-          else
-            npm version "$VERSION_TYPE" --no-git-tag-version
-          fi
-
-          NEW_VERSION=$(node -p "require('./package.json').version")
-          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "Updated to version $NEW_VERSION"
-
-      - name: Sync package versions
-        run: |
-          NEW_VERSION="${{ steps.bump.outputs.new_version }}"
-          echo "Syncing all packages to version $NEW_VERSION"
-
-          for pkg in packages/*/package.json; do
-            if [ -f "$pkg" ]; then
-              echo "Updating $pkg"
-              node -e "
-                const fs = require('fs');
-                const pkg = JSON.parse(fs.readFileSync('$pkg', 'utf8'));
-                pkg.version = '$NEW_VERSION';
-                fs.writeFileSync('$pkg', JSON.stringify(pkg, null, 2) + '\n');
-              "
-            fi
-          done
-
-      - name: Commit and push changes
-        run: |
-          git add package.json package-lock.json packages/*/package.json
-          git commit -m "chore: version: ${{ steps.bump.outputs.new_version }}"
-          git push
-```
-
-## Step 3: Configure GitHub Variables
-
-Variables are configured at different levels in GitHub Settings.
-
-### Variable Scoping
-
-| Level | Variables | Where to Configure |
-|-------|-----------|-------------------|
-| Organization | AWS_REGION, LOG_LEVEL, MODULE_LOG_LEVEL, PROJECT_SPONSOR | Settings → Actions → Variables |
-| Repository | AWS_HOSTED_ZONE, PROJECT_KEY, PROJECT_SERVICE | Settings → Actions secrets and variables → Variables |
-| Environment | AWS_ROLE_ARN, DATADOG_API_KEY_ARN, PROJECT_ENV, PROJECT_NONCE | Settings → Environments → [env] → Variables |
-
-### Creating an Environment
-
-1. Go to your repository on GitHub
-2. Navigate to **Settings → Environments**
-3. Click **New environment**
-4. Name it (e.g., `sandbox`, `development`, `production`)
-5. Click **Configure environment**
-6. Under **Environment variables**, click **Add variable** for each variable
-
-### Required Variables (Environment Level)
-
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `AWS_ROLE_ARN` | IAM role ARN for OIDC (deployment fails without this) | `arn:aws:iam::123456789:role/DeployRole` |
-| `PROJECT_ENV` | Environment identifier | `sandbox`, `development`, `production` |
-
-### Optional Variables
-
-| Variable | Level | Description | Default |
-|----------|-------|-------------|---------|
-| `AWS_REGION` | Org | AWS region | `us-east-1` |
-| `AWS_HOSTED_ZONE` | Repo | Route53 hosted zone | `example.com` |
-| `DATADOG_API_KEY_ARN` | Env | Secrets Manager ARN for Datadog | (none) |
-| `LOG_LEVEL` | Org | Application log level | `debug` |
-| `MODULE_LOG_LEVEL` | Org | Module log level | `warn` |
-| `PROJECT_KEY` | Repo | Project identifier | (from package.json name) |
-| `PROJECT_NONCE` | Env | Unique identifier for resources | (random) |
-| `PROJECT_SERVICE` | Repo | Service name | `stacks` |
-| `PROJECT_SPONSOR` | Org | Organization name | (from repository owner) |
-
-### Auto-Generated Variables
-
-These variables are set automatically from GitHub context:
-
-| Variable | Source | Description |
-|----------|--------|-------------|
-| `CDK_DEFAULT_ACCOUNT` | `${{ github.repository_owner }}` | Repository owner |
-| `CDK_DEFAULT_REGION` | `AWS_REGION` | Same as AWS region |
-| `CDK_ENV_REPO` | `${{ github.repository }}` | Repository name (owner/repo) |
-| `PROJECT_COMMIT` | `${{ github.sha }}` | Current commit SHA |
-| `PROJECT_VERSION` | `package.json` | Version from package.json |
-
-### Environment Secrets
-
-By default, no secrets are required. Dependencies add secrets as needed.
-
-Secrets are passed to CDK via `JaypieEnvSecret` construct and made available at runtime.
-
-Navigate to: **Settings → Environments → [environment] → Environment secrets**
-
-#### Example: Auth0 Integration
-
-When adding Auth0 authentication:
-
-**Environment Variables:**
-- `AUTH0_AUDIENCE` - API identifier
-- `AUTH0_CLIENT_ID` - Application client ID
-- `AUTH0_DOMAIN` - Auth0 tenant domain
-
-**Environment Secrets:**
-- `AUTH0_CLIENT_SECRET` - Application client secret
-
-Add to workflow:
-```yaml
-- name: Deploy CDK Stack
-  uses: ./.github/actions/cdk-deploy
-  with:
-    stack-name: AppStack
-  env:
-    AUTH0_CLIENT_SECRET: ${{ secrets.AUTH0_CLIENT_SECRET }}
-```
-
-### Deployment Protection Rules (Optional)
-
-You can add protection rules to any environment:
-
-- **Required reviewers**: Require manual approval before deploying
-- **Wait timer**: Delay deployment by a specified time
-- **Deployment branches**: Limit which branches can deploy
-
-### How Variables Are Resolved
-
-GitHub Actions composite actions cannot access `vars.*` directly. Variables must be passed as action inputs.
-
-The workflow passes variables to `setup-environment`, which applies defaults:
-
-```yaml
-jobs:
-  deploy:
-    environment: sandbox  # Variables from this environment
-    steps:
-      - name: Setup Environment
-        id: setup-env
-        uses: ./.github/actions/setup-environment
-        with:
-          aws-region: ${{ vars.AWS_REGION }}
-          aws-role-arn: ${{ vars.AWS_ROLE_ARN }}
-          # ... other vars
-
-      # Access resolved values via outputs
-      - name: Configure AWS
-        uses: ./.github/actions/configure-aws
-        with:
-          role-arn: ${{ steps.setup-env.outputs.aws-role-arn }}
-          aws-region: ${{ steps.setup-env.outputs.aws-region }}
-```
-
-### Environment Configuration by Target
-
-| Environment | `PROJECT_ENV` | `LOG_LEVEL` | Notes |
-|-------------|---------------|-------------|-------|
-| sandbox | `sandbox` | `debug` or `trace` | Shared testing |
-| development | `development` | `debug` | Validates multi-env deployment |
-| production | `production` | `info` | Less verbose logging |
-
-## Step 4: Configure AWS OIDC
-
-Create an IAM role in AWS that trusts GitHub Actions OIDC provider.
-
-### Trust Policy
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Principal": {
-        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
-      },
-      "Action": "sts:AssumeRoleWithWebIdentity",
-      "Condition": {
-        "StringEquals": {
-          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
-        },
-        "StringLike": {
-          "token.actions.githubusercontent.com:sub": "repo:ORG/REPO:*"
-        }
-      }
-    }
-  ]
-}
-```
-
-### Required Permissions
-
-The role needs permissions for:
-- CDK deployment (CloudFormation, IAM, Lambda, etc.)
-- Any resources your stack creates
-
-## Step 5: Verify Setup
-
-1. Push to a feature branch to trigger sandbox deployment
-2. Merge to main to trigger development deployment
-3. Create a version tag to trigger production deployment
-
-```bash
-# Test sandbox
-git checkout -b feat/test-cicd
-git push origin feat/test-cicd
-
-# Test development
-git checkout main
-git push origin main
-
-# Test production
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-## Customization
-
-### Adding Application Secrets
-
-Pass secrets to the CDK deploy action by extending `cdk-deploy/action.yml`:
-
-```yaml
-inputs:
-  api-key:
-    description: API key for external service
-    required: false
-
-# In the Deploy step:
-env:
-  API_KEY: ${{ inputs.api-key }}
-```
-
-Then in workflows:
-
-```yaml
-- name: Deploy CDK Stack
-  uses: ./.github/actions/cdk-deploy
-  with:
-    stack-name: AppStack
-    api-key: ${{ secrets.API_KEY }}
-```
-
-### Adding Framework-Specific Caching
-
-Extend `setup-node-and-cache/action.yml` for framework builds:
-
-```yaml
-- name: Cache Next.js build
-  id: cache-nextjs
-  uses: actions/cache@v4
-  with:
-    path: packages/nextjs/.next
-    key: ${{ runner.os }}-nextjs-${{ hashFiles('packages/nextjs/**/*.ts', 'packages/nextjs/**/*.tsx') }}
-```
-
-### Personal Builds
-
-For personal sandbox builds, create `deploy-personal-build.yml`:
-
-```yaml
-name: Personal Build
-
-on:
-  push:
-    branches-ignore:
-      - main
-      - develop
-      - nobuild-*
-      - nobuild/*
-      - sandbox
-      - sandbox-*
-      - sandbox/*
-
-concurrency:
-  group: deploy-personal-build-${{ github.actor }}
-
-jobs:
-  deploy:
-    environment: sandbox
-    # ... same as sandbox deploy but with PROJECT_ENV set to github.actor
-```
-
-## Troubleshooting
-
-### "The environment 'sandbox' does not exist"
-
-The environment must be created in GitHub repository settings before the workflow can reference it. See [Creating an Environment](#creating-an-environment).
-
-### OIDC Authentication Fails / "Unable to assume AWS role"
-
-- Verify `AWS_ROLE_ARN` variable is set correctly in the environment
-- Verify the OIDC provider is configured in AWS IAM
-- Check the trust policy matches your repository
-- Ensure the workflow has `id-token: write` permission
-- Verify the role has necessary permissions for CDK deployment
-
-### Cache Miss on Every Build
-
-- Verify `package-lock.json` is committed
-- Check cache key patterns match your file structure
-
-### CDK Deployment Fails
-
-- Verify AWS credentials are configured correctly
-- Check CDK is bootstrapped in the target account/region: `npx cdk bootstrap`
-- If using Datadog, verify `DATADOG_API_KEY_ARN` points to a valid secret
-- Verify the AWS role has permissions to access any Secrets Manager secrets
-- Review CloudFormation events in the AWS Console for specific errors
-
-### Error: "Cannot retrieve value from context provider hosted-zone"
-
-Stacks using context providers must extend `JaypieAppStack`, not `cdk.Stack`:
-
-```typescript
-// Wrong
-import * as cdk from "aws-cdk-lib";
-export class AppStack extends cdk.Stack { ... }
-
-// Correct
-import { JaypieAppStack } from "@jaypie/constructs";
-export class AppStack extends JaypieAppStack { ... }
-```
-
-`JaypieAppStack` automatically sets `env` with `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION`.
-
-### Variables Not Being Applied
-
-- Composite actions cannot access `vars.*` directly
-- Verify variables are passed as inputs to `setup-environment`
-- Check the environment name in the job matches the GitHub environment name
-- Verify variable names match exactly (case-sensitive)
-