@jaypie/mcp 0.2.12 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.2.12",
+  "version": "0.3.1",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/prompts/Jaypie_CDK_Constructs_and_Patterns.md

@@ -106,7 +106,6 @@ For streaming responses (SSE, real-time updates), use `createLambdaStreamHandler
 
 ```typescript
 import { JaypieExpressLambda, JaypieDistribution } from "@jaypie/constructs";
-import * as lambda from "aws-cdk-lib/aws-lambda";
 
 // Create Lambda (handler uses createLambdaStreamHandler internally)
 const streamingApi = new JaypieExpressLambda(this, "StreamingApi", {
@@ -114,10 +113,10 @@ const streamingApi = new JaypieExpressLambda(this, "StreamingApi", {
   handler: "index.handler",
 });
 
-// Use with CloudFront and RESPONSE_STREAM invoke mode
+// Use with CloudFront and streaming enabled
 new JaypieDistribution(this, "Distribution", {
   handler: streamingApi,
-  invokeMode: lambda.InvokeMode.RESPONSE_STREAM,
+  streaming: true,
   host: "api.example.com",
   zone: "example.com",
 });
@@ -135,13 +134,13 @@ const streamingLambda = new JaypieLambda(this, "StreamingFunction", {
 
 const functionUrl = streamingLambda.addFunctionUrl({
   authType: FunctionUrlAuthType.NONE,
-  invokeMode: InvokeMode.RESPONSE_STREAM,
+  invokeMode: InvokeMode.RESPONSE_STREAM, // Direct Function URL still uses InvokeMode
 });
 
 new cdk.CfnOutput(this, "StreamingUrl", { value: functionUrl.url });
 ```
 
-Note: Streaming requires Lambda Function URLs (not API Gateway). `JaypieDistribution` uses Function URLs by default.
+Note: Streaming requires Lambda Function URLs (not API Gateway). `JaypieDistribution` uses Function URLs by default and accepts `streaming: true` for a cleaner API.
 
 ### Stack Types
 

package/prompts/Jaypie_CICD_with_GitHub_Actions.md

@@ -6,6 +6,14 @@ description: conventions around deployment and environment variables, especially
 
 Reference for Jaypie CI/CD conventions. For setup instructions, see `Jaypie_Init_CICD_with_GitHub_Actions.md`.
 
+## 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 |
+
 ## Jaypie Environments
 
 Jaypie assumes multiple deployed environments:
@@ -19,11 +27,21 @@ Jaypie assumes multiple deployed environments:
 
 ## Naming Conventions
 
-Workflow files lead with the most important keyword and end with the environment:
-- `deploy-personal-build.yml`
-- `deploy-sandbox.yml`
-- `deploy-production.yml`
-- `npm-deploy.yml`
+### Workflow File Naming
+
+| Pattern | Purpose | Example |
+|---------|---------|---------|
+| `deploy-env-$ENV.yml` | Deploy all stacks to an environment | `deploy-env-sandbox.yml` |
+| `deploy-$ENV.yml` | Legacy alias for environment deploy | `deploy-sandbox.yml` |
+| `deploy-stack-$STACK.yml` | Deploy specific stack content | `deploy-stack-documentation.yml` |
+
+### Tag Naming
+
+| Pattern | Purpose | Example |
+|---------|---------|---------|
+| `v*` | Production version release | `v1.2.3` |
+| `$ENV-*` | Deploy to specific environment | `sandbox-hotfix` |
+| `stack-$STACK-*` | Deploy specific stack | `stack-documentation-v1.0.0` |
 
 Always prefer full words for maximum clarity.
 
@@ -54,11 +72,17 @@ jobs:        # alphabetical
 
 | Environment | Trigger |
 |-------------|---------|
-| production | tags: `v*` |
-| development | branches: `[main]` |
-| sandbox | branches: `[main, develop, sandbox, sandbox-*, sandbox/*]` |
+| production | tags: `v*`, `production-*` |
+| development | branches: `[main, development/*]`, tags: `development-*` |
+| sandbox | branches: `[feat/*, sandbox/*]`, tags: `sandbox-*` |
 | personal | branches-ignore: `[main, develop, nobuild-*, nobuild/*, sandbox, sandbox-*, sandbox/*]` |
 
+### Stack Triggers
+
+| Stack | Trigger |
+|-------|---------|
+| documentation | Push to `main` with path filter, tags: `stack-documentation-*` |
+
 ### Dependencies
 
 | Environment | Lint/Test Dependency |
@@ -74,14 +98,20 @@ Use `npm run lint` and `npm run test`. Verify the test script uses `vitest run`
 
 ## Concurrency
 
-New builds cancel in-progress builds. Environments run in parallel between each other but concurrently within an environment.
+Use concurrency groups without `cancel-in-progress` to avoid stuck deployments. Environments run in parallel between each other but concurrently within an environment.
+
+### Environment Builds
+
+```yaml
+concurrency:
+  group: deploy-env-production
+```
 
-### Static Builds
+### Stack Builds
 
 ```yaml
 concurrency:
-  group: deploy-production
-  cancel-in-progress: true
+  group: deploy-stack-documentation-${{ github.event.inputs.environment || 'development' }}
 ```
 
 ### Personal Builds
@@ -89,7 +119,6 @@ concurrency:
 ```yaml
 concurrency:
   group: deploy-personal-build-${{ github.actor }}
-  cancel-in-progress: true
 ```
 
 ## Personal Builds
@@ -122,6 +151,48 @@ Create GitHub environments matching deployment targets:
 
 Each environment contains variables and secrets specific to that deployment target.
 
+## GitHub Variable Scoping
+
+Variables are configured at different levels in GitHub Settings:
+
+### Organization Level
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AWS_REGION` | AWS region | `us-east-1` |
+| `LOG_LEVEL` | Application log level | `debug` |
+| `MODULE_LOG_LEVEL` | Module log level | `warn` |
+| `PROJECT_SPONSOR` | Organization name | `finlaysonstudio` |
+
+### Repository Level
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AWS_HOSTED_ZONE` | Route53 hosted zone | `example.com` |
+| `PROJECT_KEY` | Project identifier | `myapp` |
+| `PROJECT_SERVICE` | Service name | `stacks` |
+
+### Environment Level
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `AWS_ROLE_ARN` | IAM role ARN for OIDC | Yes |
+| `DATADOG_API_KEY_ARN` | Datadog API key ARN in Secrets Manager | No |
+| `PROJECT_ENV` | Environment identifier | Yes |
+| `PROJECT_NONCE` | Unique resource identifier | No |
+
+### 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 Variables Reference
 
 ### Application Variables
@@ -169,6 +240,8 @@ Follow naming from vendor documentation. If documentation does not reference env
 
 ## Secrets
 
+By default, no secrets are required. Dependencies add secrets as needed.
+
 ### Secret Naming
 
 Secrets follow the same conventions as variables. Use `SECRET_` prefix for secrets that will be resolved at runtime:
@@ -177,6 +250,8 @@ Secrets follow the same conventions as variables. Use `SECRET_` prefix for secre
 
 ### Passing Secrets
 
+Secrets are passed to CDK via `JaypieEnvSecret` construct and made available at runtime.
+
 Pass secrets only to steps that need them:
 
 ```yaml
@@ -190,6 +265,30 @@ Pass secrets only to steps that need them:
 
 Never expose secrets in logs or workflow outputs.
 
+### Adding Dependency Secrets
+
+When adding dependencies that require secrets, update the workflow accordingly.
+
+#### Example: Auth0 Integration
+
+**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 }}
+```
+
 ## CDK Stack Names
 
 The `stack-name` parameter in deploy workflows must match the stack ID defined in `packages/cdk/bin/cdk.ts`:
@@ -200,7 +299,7 @@ new AppStack(app, "AppStack");  // "AppStack" is the stack ID
 ```
 
 ```yaml
-# deploy-*.yml
+# deploy-env-*.yml
 - name: Deploy CDK Stack
   uses: ./.github/actions/cdk-deploy
   with:
@@ -209,6 +308,34 @@ new AppStack(app, "AppStack");  // "AppStack" is the stack ID
 
 If you rename the stack ID (e.g., to "MyProjectAppStack" for clarity in AWS), update all deploy workflows to match. Mismatched names cause "No stacks match the name(s)" errors.
 
+## Environment-Aware Hostnames
+
+Jaypie CDK constructs use `envHostname()` from `@jaypie/constructs` to determine deployment hostnames based on `PROJECT_ENV`:
+
+| `PROJECT_ENV` | Example Hostname |
+|---------------|------------------|
+| `production` | `example.com` (apex domain) |
+| `sandbox` | `sandbox.example.com` |
+| `development` | `development.example.com` |
+| `personal` | `personal.example.com` |
+
+**CRITICAL**: If `PROJECT_ENV` is not set or is set incorrectly in the GitHub environment, deployments may target the wrong hostname (e.g., deploying sandbox changes to production apex).
+
+### How It Works
+
+1. The `setup-environment` action reads `${{ vars.PROJECT_ENV }}` from the GitHub environment
+2. This is exported as `PROJECT_ENV` to `$GITHUB_ENV`
+3. CDK constructs read `process.env.PROJECT_ENV` via `envHostname()`
+4. For production, the environment prefix is omitted (apex domain)
+5. For all other environments, the prefix is prepended
+
+### Troubleshooting Wrong Hostname
+
+If deployment targets the wrong hostname:
+1. Go to GitHub Settings → Environments
+2. Select the environment (sandbox, development, production)
+3. Verify `PROJECT_ENV` variable matches the environment name exactly
+
 ## Integrations
 
 ### AWS