@jaypie/mcp 0.7.4 → 0.7.7

package/skills/cicd-deploy.md

@@ -0,0 +1,332 @@
+---
+description: CDK deployment workflows for sandbox and production
+related: cicd, cicd-actions, cicd-environments, cdk
+---
+
+# CDK Deployment Workflows
+
+Complete workflow templates for deploying CDK stacks to sandbox and production environments.
+
+## deploy-sandbox.yml
+
+Deploys to sandbox on feature branches and main.
+
+```yaml
+name: deploy-sandbox
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/*'
+      - 'fix/*'
+      - 'sandbox/*'
+
+concurrency:
+  group: deploy-sandbox-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-and-cache
+      - uses: ./.github/actions/npm-install-build
+        with:
+          skip-build: 'true'
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-and-cache
+      - uses: ./.github/actions/npm-install-build
+        with:
+          skip-build: 'true'
+      - run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22, 24, 25]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-and-cache
+        with:
+          node-version: ${{ matrix.node-version }}
+      - uses: ./.github/actions/npm-install-build
+      - run: npm test
+
+  deploy:
+    needs: [lint, typecheck, test]
+    runs-on: ubuntu-latest
+    environment: sandbox
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-environment
+        with:
+          project-key: my-project
+          project-env: sandbox
+
+      - uses: ./.github/actions/configure-aws
+        with:
+          role-arn: ${{ vars.AWS_ROLE_ARN }}
+          region: ${{ vars.AWS_REGION || 'us-east-1' }}
+
+      - uses: ./.github/actions/setup-node-and-cache
+
+      - uses: ./.github/actions/npm-install-build
+
+      - uses: ./.github/actions/cdk-deploy
+        with:
+          stack-name: '*-sandbox-*'
+```
+
+## deploy-production.yml
+
+Deploys to production on release tags.
+
+```yaml
+name: deploy-production
+
+on:
+  push:
+    tags:
+      - 'production-*'
+      - 'v0.*'
+      - 'v1.*'
+      - 'v2.*'
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-and-cache
+      - uses: ./.github/actions/npm-install-build
+        with:
+          skip-build: 'true'
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-and-cache
+      - uses: ./.github/actions/npm-install-build
+        with:
+          skip-build: 'true'
+      - run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22, 24, 25]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-node-and-cache
+        with:
+          node-version: ${{ matrix.node-version }}
+      - uses: ./.github/actions/npm-install-build
+      - run: npm test
+
+  deploy:
+    needs: [lint, typecheck, test]
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-environment
+        with:
+          project-key: my-project
+          project-env: production
+
+      - uses: ./.github/actions/configure-aws
+        with:
+          role-arn: ${{ vars.AWS_ROLE_ARN }}
+          region: ${{ vars.AWS_REGION || 'us-east-1' }}
+
+      - uses: ./.github/actions/setup-node-and-cache
+
+      - uses: ./.github/actions/npm-install-build
+
+      - uses: ./.github/actions/cdk-deploy
+        with:
+          stack-name: '*-production-*'
+```
+
+## version.yml
+
+Manually trigger version bumps across packages.
+
+```yaml
+name: version
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_type:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      packages:
+        description: 'Packages to version (comma-separated, or "all")'
+        required: false
+        default: 'all'
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: ./.github/actions/setup-node-and-cache
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump versions
+        run: |
+          PACKAGES="${{ github.event.inputs.packages }}"
+          VERSION_TYPE="${{ github.event.inputs.version_type }}"
+
+          if [ "$PACKAGES" = "all" ]; then
+            # Bump all packages in packages/ directory
+            for pkg in packages/*/package.json; do
+              dir=$(dirname "$pkg")
+              echo "Bumping $dir"
+              npm version $VERSION_TYPE --workspace "$dir" --no-git-tag-version
+            done
+          else
+            # Bump specific packages
+            IFS=',' read -ra PKG_ARRAY <<< "$PACKAGES"
+            for pkg in "${PKG_ARRAY[@]}"; do
+              pkg=$(echo "$pkg" | xargs)  # trim whitespace
+              echo "Bumping packages/$pkg"
+              npm version $VERSION_TYPE --workspace "packages/$pkg" --no-git-tag-version
+            done
+          fi
+
+      - name: Update package-lock.json
+        run: npm i --package-lock-only
+
+      - name: Commit and push
+        run: |
+          git add .
+          git commit -m "chore: bump versions (${{ github.event.inputs.version_type }})"
+          git push
+```
+
+## Environment-Specific Stack Naming
+
+Use consistent stack naming with environment and nonce:
+
+```typescript
+// stacks/cdk/src/app.ts
+const env = process.env.PROJECT_ENV || "sandbox";
+const nonce = process.env.PROJECT_NONCE || "dev";
+
+new ApiStack(app, `api-${env}-${nonce}`, {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION,
+  },
+});
+```
+
+This produces stack names like:
+- `api-sandbox-feat-new-feature`
+- `api-sandbox-main`
+- `api-production-prod`
+
+## Deployment Flow
+
+### Sandbox Flow
+
+```
+feat/branch → push → lint/test → deploy → sandbox stack
+      ↓
+main branch → push → lint/test → deploy → sandbox stack
+```
+
+### Production Flow
+
+```
+main branch → tag v1.0.0 → push → lint/test → deploy → production stack
+                                      ↓
+                            (requires approval)
+```
+
+## Adding Approval Gates
+
+For production, add required reviewers in GitHub Environment settings:
+
+1. Go to **Settings** → **Environments** → **production**
+2. Enable **Required reviewers**
+3. Add team members who can approve deployments
+
+## Notifications
+
+Add Slack notifications on deploy:
+
+```yaml
+- name: Notify Slack
+  if: success()
+  uses: slackapi/slack-github-action@v1
+  with:
+    payload: |
+      {
+        "text": "Deployed ${{ github.repository }} to ${{ vars.PROJECT_ENV }}",
+        "blocks": [
+          {
+            "type": "section",
+            "text": {
+              "type": "mrkdwn",
+              "text": "*Deployment Complete*\nRepo: ${{ github.repository }}\nEnv: ${{ vars.PROJECT_ENV }}\nRef: ${{ github.ref_name }}"
+            }
+          }
+        ]
+      }
+  env:
+    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+```
+
+## Rollback Strategy
+
+For quick rollbacks, use git tags:
+
+```bash
+# Tag current production state before deploying
+git tag production-backup-$(date +%Y%m%d)
+
+# If rollback needed, push previous tag
+git push origin production-backup-20250131:refs/tags/production-rollback
+```
+
+This triggers the production workflow with the previous code.

package/skills/cicd-environments.md

@@ -0,0 +1,184 @@
+---
+description: GitHub Environments configuration for CDK deployments
+related: cicd, cicd-actions, cicd-deploy, variables
+---
+
+# GitHub Environments Configuration
+
+GitHub Environments provide deployment-specific variables for Jaypie CDK workflows. Each environment (sandbox, production) has its own set of variables.
+
+## Required Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AWS_ROLE_ARN` | OIDC role ARN for assuming AWS credentials |
+
+## Optional Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AWS_REGION` | `us-east-1` | AWS region for deployment |
+| `LOG_LEVEL` | `trace` (sandbox) / `info` (production) | Application log level |
+| `PROJECT_CHAOS` | `full` (sandbox) / `none` (production) | Chaos engineering mode |
+| `PROJECT_ENV` | Environment name | Environment identifier |
+| `PROJECT_NONCE` | Branch name or `prod` | Unique identifier for resources |
+
+## Environment Setup
+
+### Create Environment
+
+1. Navigate to **Settings** → **Environments**
+2. Click **New environment**
+3. Enter environment name (e.g., `sandbox`, `production`)
+4. Click **Configure environment**
+
+### Add Environment Variables
+
+1. In environment settings, click **Add variable**
+2. Add required and optional variables:
+
+**Sandbox Environment:**
+
+```
+AWS_ROLE_ARN      = arn:aws:iam::123456789012:role/GitHubActions-Sandbox
+AWS_REGION        = us-east-1
+PROJECT_ENV       = sandbox
+LOG_LEVEL         = trace
+PROJECT_CHAOS     = full
+```
+
+**Production Environment:**
+
+```
+AWS_ROLE_ARN      = arn:aws:iam::123456789012:role/GitHubActions-Production
+AWS_REGION        = us-east-1
+PROJECT_ENV       = production
+LOG_LEVEL         = info
+PROJECT_CHAOS     = none
+```
+
+### Configure Deployment Protection (Production)
+
+For production environments:
+
+1. Enable **Required reviewers** and add approvers
+2. Enable **Wait timer** if needed
+3. Limit deployment branches to `main`, `production-*`, `v*`
+
+## AWS OIDC Role Setup
+
+### Trust Policy
+
+Create an IAM role with this trust policy to allow GitHub Actions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "Federated": "arn:aws:iam::123456789012: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:*"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Role Permissions
+
+Attach policies for CDK deployment:
+
+- `PowerUserAccess` for CDK deployments, or scoped custom policy
+- `iam:PassRole` for Lambda execution roles
+
+## Workflow Environment Usage
+
+Reference environments in workflow files:
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: sandbox
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-east-1' }}
+```
+
+## Variable Precedence
+
+Variables are resolved in order:
+
+1. Job/step `env:` block (highest priority)
+2. Workflow-level `env:` block
+3. Environment variables (`vars.*`)
+4. Repository variables
+5. Default values in composite actions
+
+## Troubleshooting
+
+### "No credentials" Error
+
+**Symptoms:** `Error: Credentials could not be loaded`
+
+**Causes:**
+- Missing `id-token: write` permission
+- Incorrect `AWS_ROLE_ARN`
+- Role trust policy not configured for repository
+
+**Fix:** Verify OIDC role trust policy matches repository and permissions include `id-token: write`.
+
+### "Access Denied" During Deploy
+
+**Symptoms:** CDK deploy fails with permission errors
+
+**Causes:**
+- Role lacks required permissions
+- Cross-account access not configured
+- Resource policy restrictions
+
+**Fix:** Review CloudTrail logs for specific denied action and update role policy.
+
+### Variables Not Resolving
+
+**Symptoms:** `${{ vars.AWS_ROLE_ARN }}` is empty
+
+**Causes:**
+- Variable not defined in environment
+- Environment not specified in job
+- Typo in variable name
+
+**Fix:** Verify environment is set and variable exists with exact spelling.
+
+### Wrong Environment Used
+
+**Symptoms:** Deploying to wrong environment
+
+**Causes:**
+- `environment:` key missing or incorrect in job
+- Branch protection rules not limiting deployments
+
+**Fix:** Add explicit `environment:` to job and configure branch restrictions.
+
+## Best Practices
+
+1. **Use separate AWS accounts** for sandbox and production
+2. **Limit production role permissions** to specific resources
+3. **Enable deployment protection** for production
+4. **Use environment-specific secrets** when needed
+5. **Document role ARNs** in repository README or wiki

package/skills/cicd.md

@@ -1,12 +1,20 @@
 ---
 description: GitHub Actions CI/CD workflows
-related: tests, cdk
+related: cicd-actions, cicd-deploy, cicd-environments, cdk, tests
 ---
 
 # CI/CD with GitHub Actions
 
 Jaypie projects use GitHub Actions for continuous integration and deployment.
 
+## Sub-Skills
+
+| Skill | Description |
+|-------|-------------|
+| `cicd-actions` | Reusable composite actions for workflows |
+| `cicd-deploy` | CDK deployment workflows (sandbox, production) |
+| `cicd-environments` | GitHub Environments configuration |
+
 ## Standard Workflows
 
 ### npm-check.yml

package/skills/development.md

@@ -1,6 +1,6 @@
 ---
 description: Coding standards, testing, and documentation
-related: documentation, errors, logs, mocks, style, tests
+related: documentation, errors, logs, mocks, monorepo, style, subpackage, tests
 ---
 
 # Development
@@ -15,5 +15,7 @@ Coding standards and practices for Jaypie projects.
 | `errors` | Error handling with @jaypie/errors |
 | `logs` | Logging patterns and conventions |
 | `mocks` | Mock patterns via @jaypie/testkit |
+| `monorepo` | Initialize a Jaypie monorepo project |
 | `style` | Code style conventions |
+| `subpackage` | Create a subpackage within a monorepo |
 | `tests` | Testing patterns with Vitest |

package/skills/infrastructure.md

@@ -1,6 +1,6 @@
 ---
 description: AWS, CDK, CI/CD, and observability
-related: aws, cdk, cicd, datadog, dns, dynamodb, secrets, variables, websockets
+related: aws, cdk, cicd, cicd-actions, cicd-deploy, cicd-environments, datadog, dns, dynamodb, secrets, variables, websockets
 ---
 
 # Infrastructure
@@ -13,7 +13,10 @@ Cloud infrastructure and deployment patterns.
 |-------|-------------|
 | `aws` | AWS integration and cloud services |
 | `cdk` | CDK constructs and deployment |
-| `cicd` | GitHub Actions workflows |
+| `cicd` | GitHub Actions workflows (overview) |
+| `cicd-actions` | Reusable composite actions |
+| `cicd-deploy` | CDK deployment workflows |
+| `cicd-environments` | GitHub Environments configuration |
 | `datadog` | Datadog and observability |
 | `dns` | DNS and domain configuration |
 | `dynamodb` | DynamoDB patterns and queries |