@jaypie/mcp 0.1.10 → 0.2.1

package/prompts/Jaypie_CDK_Constructs_and_Patterns.md

@@ -33,10 +33,13 @@ new JaypieLambda(this, "MyFunction", {
 ```
 
 Features:
-- Automatic Datadog integration when `DATADOG_API_KEY_ARN` exists
+- Automatic Datadog integration when `DATADOG_API_KEY_ARN` or `CDK_ENV_DATADOG_API_KEY_ARN` exists
 - Default environment variables from `PROJECT_*` settings
-- Provisioned concurrency support
-- Secrets management via `JaypieEnvSecret`
+- Provisioned concurrency support via `provisionedConcurrentExecutions`
+- Secrets management via `secrets` array (JaypieEnvSecret[])
+- Direct secret integration via `envSecrets` object
+- Parameter Store/Secrets Manager layer via `paramsAndSecrets`
+- VPC, security groups, filesystem, and all standard Lambda configuration options
 
 ### Queue-Lambda Patterns
 
@@ -45,18 +48,33 @@ Use `JaypieQueuedLambda` for SQS-triggered Lambdas:
 new JaypieQueuedLambda(this, "Worker", {
   code: "dist",
   fifo: true,
-  batchSize: 10
+  batchSize: 10,
+  visibilityTimeout: Duration.seconds(900)
 });
 ```
 
+Features:
+- Auto-creates SQS queue and connects to Lambda
+- Implements both `lambda.IFunction` and `sqs.IQueue` interfaces
+- Auto-injects `CDK_ENV_QUEUE_URL` environment variable
+- Grants consume and send permissions to Lambda
+
 Use `JaypieBucketQueuedLambda` for S3-triggered processing:
 ```typescript
 new JaypieBucketQueuedLambda(this, "Processor", {
   code: "dist",
-  bucketName: "my-bucket"
+  bucketName: "my-bucket",
+  bucketOptions: { versioned: true } // Optional S3 configuration
 });
 ```
 
+Features:
+- Extends `JaypieQueuedLambda` with S3 bucket and event notifications
+- Forces non-FIFO queue (S3 limitation)
+- Auto-injects `CDK_ENV_BUCKET_NAME` environment variable
+- Grants read/write permissions to Lambda
+- Implements `s3.IBucket` interface
+
 ### API Gateway
 
 Use `JaypieApiGateway` for REST APIs with custom domains:
@@ -101,22 +119,37 @@ new JaypieEnvSecret(this, "API_KEY");
 // Explicit configuration
 new JaypieEnvSecret(this, "ApiKey", {
   envKey: "API_KEY",
-  provider: true,  // Exports for other stacks
-  consumer: false  // Imports from provider stack
+  provider: true,  // Exports for other stacks (default: PROJECT_ENV=sandbox)
+  consumer: false, // Imports from provider stack (default: PROJECT_ENV=personal)
+  value: "secret-value", // Direct value (alternative to envKey)
+  generateSecretString: {}, // Auto-generate secret
 });
 ```
 
+Provider/consumer pattern:
+- Provider stacks (sandbox) create and export secrets
+- Consumer stacks (personal/ephemeral) import secrets by name
+- Export name format: `env-${PROJECT_ENV}-${PROJECT_KEY}-${id}`
+
 ### Web Hosting
 
 Use `JaypieWebDeploymentBucket` for static sites:
 ```typescript
 new JaypieWebDeploymentBucket(this, "WebSite", {
   host: "www.example.com",
-  zone: "example.com"
+  zone: "example.com",
+  certificate: true // Creates new cert; can pass ICertificate or false
 });
 ```
 
-Creates S3 bucket, CloudFront distribution, and DNS records.
+Features:
+- Creates S3 bucket with website hosting enabled
+- Creates CloudFront distribution with SSL certificate
+- Creates Route53 DNS records
+- Auto-creates GitHub deployment role when `CDK_ENV_REPO` is set
+- Production environments get optimized caching (index.html excluded)
+- Implements `s3.IBucket` interface
+- Can use `CDK_ENV_WEB_HOST` or `CDK_ENV_WEB_SUBDOMAIN` + hosted zone
 
 ### Hosted Zones
 
@@ -130,32 +163,123 @@ new JaypieHostedZone(this, "Zone", {
 ## Environment Variables
 
 Configure constructs via environment:
-- `CDK_ENV_API_HOST_NAME`: API domain name
+
+### API Configuration
+- `CDK_ENV_API_HOST_NAME`: Full API domain name
+- `CDK_ENV_API_SUBDOMAIN`: API subdomain (combined with CDK_ENV_API_HOSTED_ZONE)
 - `CDK_ENV_API_HOSTED_ZONE`: API hosted zone
-- `CDK_ENV_WEB_SUBDOMAIN`: Web subdomain
+
+### Web Configuration
+- `CDK_ENV_WEB_HOST`: Full web domain name
+- `CDK_ENV_WEB_SUBDOMAIN`: Web subdomain (combined with CDK_ENV_WEB_HOSTED_ZONE)
 - `CDK_ENV_WEB_HOSTED_ZONE`: Web hosted zone
-- `CDK_ENV_REPO`: GitHub repository for deployment roles
-- `DATADOG_API_KEY_ARN`: Datadog API key secret ARN
-- `PROJECT_ENV`: Environment name (sandbox, production)
+
+### General DNS
+- `CDK_ENV_HOSTED_ZONE`: Fallback hosted zone (used by API and Web if specific zones not set)
+
+### Deployment
+- `CDK_ENV_REPO`: GitHub repository for deployment roles (format: owner/repo)
+
+### Datadog Integration
+- `DATADOG_API_KEY_ARN`: Datadog API key secret ARN (primary)
+- `CDK_ENV_DATADOG_API_KEY_ARN`: Datadog API key secret ARN (fallback)
+- `CDK_ENV_DATADOG_ROLE_ARN`: Datadog IAM role ARN for extended permissions
+
+### Project Configuration
+- `PROJECT_ENV`: Environment name (sandbox, production, personal, etc.)
 - `PROJECT_KEY`: Project identifier
 - `PROJECT_SERVICE`: Service name
 - `PROJECT_SPONSOR`: Cost allocation tag
+- `PROJECT_NONCE`: Unique identifier for ephemeral builds
+
+### Infrastructure Tracking
+- `CDK_ENV_INFRASTRUCTURE_STACK_SHA`: Git SHA for infrastructure stack tagging
+
+### Auto-Injected (Set by Constructs)
+- `CDK_ENV_BUCKET_NAME`: S3 bucket name (set by JaypieBucketQueuedLambda)
+- `CDK_ENV_QUEUE_URL`: SQS queue URL (set by JaypieQueuedLambda)
 
 ## Helper Functions
 
 Use helper utilities:
 ```typescript
-import { constructStackName, constructEnvName, isEnv } from "@jaypie/constructs/helpers";
+import { constructStackName, constructEnvName, isEnv } from "@jaypie/constructs";
 
 const stackName = constructStackName("app");  // project-env-app
 const resourceName = constructEnvName("bucket");  // project-env-bucket
 const isProduction = isEnv("production");
 ```
 
+## Additional Helper Functions
+
+Available from `@jaypie/constructs`:
+
+```typescript
+import {
+  isProductionEnv,
+  isSandboxEnv,
+  jaypieLambdaEnv,
+  constructTagger,
+  resolveHostedZone,
+  resolveDatadogLayers,
+  resolveDatadogForwarderFunction,
+  resolveDatadogLoggingDestination,
+  resolveParamsAndSecrets,
+  extendDatadogRole,
+  envHostname,
+  isValidHostname,
+  isValidSubdomain,
+  mergeDomain,
+} from "@jaypie/constructs";
+```
+
+Common usage:
+- `isProductionEnv()`: Returns true if PROJECT_ENV is production
+- `isSandboxEnv()`: Returns true if PROJECT_ENV is sandbox
+- `jaypieLambdaEnv({ initialEnvironment })`: Merges PROJECT_* vars into Lambda env
+- `resolveHostedZone(scope, { zone })`: Gets IHostedZone from string or object
+- `extendDatadogRole(lambda)`: Adds Datadog IAM permissions when CDK_ENV_DATADOG_ROLE_ARN set
+
+## Additional Constructs
+
+Other constructs available but not commonly used:
+
+### Base and Infrastructure
+- `JaypieStack`: Base stack with standard tagging and configuration
+
+### Specialized Secrets
+- `JaypieDatadogSecret`: Datadog API key secret management
+- `JaypieMongoDbSecret`: MongoDB connection string secret
+- `JaypieOpenAiSecret`: OpenAI API key secret
+- `JaypieTraceSigningKeySecret`: Trace signing key secret
+
+### DNS and Networking
+- `JaypieDnsRecord`: Create individual DNS records in hosted zones
+
+### Deployment and CI/CD
+- `JaypieGitHubDeployRole`: GitHub Actions OIDC deployment role
+
+### Event-Driven
+- `JaypieEventsRule`: EventBridge rules with standard configuration
+
+### Advanced Features
+- `JaypieNextJs`: Next.js application deployment (uses cdk-nextjs-standalone)
+- `JaypieDatadogForwarder`: Datadog log forwarder Lambda setup
+- `JaypieOrganizationTrail`: CloudTrail organization-wide trail
+- `JaypieSsoPermissions`: AWS IAM Identity Center permission sets
+- `JaypieSsoSyncApplication`: SSO sync application for Google Workspace
+- `JaypieAccountLoggingBucket`: Account-level centralized logging bucket
+- `JaypieDatadogBucket`: Datadog-specific S3 bucket
+- `JaypieStaticWebBucket`: Static web bucket (simpler than JaypieWebDeploymentBucket)
+- `JaypieDistribution`: CloudFront distribution construct
+
 ## Tagging Strategy
 
 Constructs apply standard tags:
-- `role`: Resource role (api, processing, networking, hosting)
-- `vendor`: External service provider
-- `service`: Service category
-- `sponsor`: Cost allocation
+- `role`: Resource role (api, processing, networking, hosting, deploy, monitoring, security, storage, stack)
+- `vendor`: External service provider (auth0, datadog, mongodb, openai, knowtrace)
+- `service`: Service category (datadog, infrastructure, libraries, sso, trace)
+- `sponsor`: Cost allocation
+- `project`: Project identifier (from PROJECT_KEY)
+- `env`: Environment name (from PROJECT_ENV)
+- `stackSha`: Git SHA for infrastructure stacks (from CDK_ENV_INFRASTRUCTURE_STACK_SHA)

package/prompts/Jaypie_Express_Package.md

@@ -5,7 +5,7 @@ globs: packages/express/**
 
 # Jaypie Express Package
 
-Jaypie provides Express utilities through `@jaypie/express` (also available via `jaypie`). The primary export is `expressHandler`, a wrapper that adds error handling, logging, lifecycle hooks, and response formatting to Express route handlers.
+Jaypie provides Express utilities through `@jaypie/express` (also available via `jaypie`). The main export is `expressHandler`, a function that wraps Express route handlers to add error handling, logging, lifecycle hooks, and automatic response formatting.
 
 ## Installation
 
@@ -17,7 +17,7 @@ npm install @jaypie/express
 
 ## expressHandler
 
-The core of Jaypie Express. Wraps route handlers with error handling, logging, and lifecycle management.
+Wraps Express route handlers with error handling, logging, and lifecycle management.
 
 ### Basic Usage
 
@@ -35,7 +35,7 @@ app.get("/hello", myRoute);
 
 ### Return Value Handling
 
-expressHandler automatically formats responses:
+expressHandler automatically formats responses based on return values:
 
 | Return Value | HTTP Status | Response |
 |--------------|-------------|----------|
@@ -43,10 +43,13 @@ expressHandler automatically formats responses:
 | Array | 200 | JSON body |
 | String (JSON) | 200 | Parsed JSON |
 | String (other) | 200 | Text body |
+| Number | 200 | Sent via `res.send()` |
 | `true` | 201 Created | Empty |
 | `null`, `undefined`, `false` | 204 No Content | Empty |
 | Object with `.json()` method | 200 | Result of `.json()` |
 
+**Note:** If you call `res.json()`, `res.send()`, or `res.end()` directly in your handler, expressHandler will log a warning but respect your call. Prefer using return values instead.
+
 ### Options
 
 ```typescript
@@ -75,9 +78,16 @@ const handler2 = expressHandler(options, async (req, res) => {
 
 ## Lifecycle Hooks
 
+Lifecycle hooks execute in this order:
+1. Setup functions (in array order)
+2. Locals functions (in object key order, after all setup)
+3. Validate functions (in array order)
+4. Main handler
+5. Teardown functions (always run, even on error)
+
 ### Setup Functions
 
-Run before the main handler. Use for initialization, authentication checks, or setting up request context.
+Run before validation and the main handler. Use for initialization, authentication checks, or setting up request context.
 
 ```typescript
 import { expressHandler } from "jaypie";
@@ -105,7 +115,7 @@ const handler = expressHandler(
 
 ### Teardown Functions
 
-Run after the main handler completes (success or error). Use for cleanup.
+Run after the main handler completes. Teardown functions execute regardless of success or error, making them suitable for cleanup operations.
 
 ```typescript
 import type { JaypieHandlerTeardown } from "jaypie";
@@ -157,7 +167,7 @@ const handler = expressHandler(
 
 ### Locals
 
-Set values on `req.locals`. Values can be static or functions that receive `(req, res)`.
+Set values on `req.locals`. Values can be static or functions that receive `(req, res)`. Locals functions are called AFTER setup functions.
 
 ```typescript
 import type { ExpressHandlerLocals } from "jaypie";
@@ -176,7 +186,7 @@ const handler = expressHandler(
   {
     locals: {
       apiVersion: "v1",          // Static value
-      user: getUser,             // Function called during setup
+      user: getUser,             // Function called after setup
     },
   }
 );
@@ -184,7 +194,7 @@ const handler = expressHandler(
 
 ## CORS Helper
 
-Configure CORS middleware with Jaypie conventions.
+Configures CORS middleware using the `cors` npm package with automatic origin validation.
 
 ```typescript
 import { cors } from "jaypie";
@@ -199,17 +209,23 @@ app.use(cors({ origin: "*" }));
 // Specific origin
 app.use(cors({ origin: "https://example.com" }));
 
+// Multiple origins
+app.use(cors({ origin: ["https://example.com", "https://app.example.com"] }));
+
 // Custom configuration
 const corsConfig: CorsConfig = {
   origin: "https://api.example.com",
-  // Additional cors options
+  overrides: {
+    // Additional options passed to the cors package
+    credentials: true,
+  },
 };
 app.use(cors(corsConfig));
 ```
 
 Environment variables:
-- `BASE_URL` or `PROJECT_BASE_URL`: Default allowed origin
-- `PROJECT_ENV=sandbox` or `PROJECT_SANDBOX_MODE=true`: Allows localhost
+- `BASE_URL` or `PROJECT_BASE_URL`: Default allowed origins
+- `PROJECT_ENV=sandbox` or `PROJECT_SANDBOX_MODE=true`: Allows localhost origins (including ports)
 
 ## Pre-built Routes
 
@@ -319,6 +335,7 @@ import {
   notFoundRoute,
   NotFoundError,
   ForbiddenError,
+  UnauthorizedError,
   log,
 } from "jaypie";
 import type {
@@ -378,10 +395,13 @@ export default app;
 
 ## Response Headers
 
-expressHandler automatically sets:
-- `X-Powered-By: @jaypie/express`
-- `X-Project-Handler: {name}` (if name option provided)
-- `X-Project-Invocation: {uuid}` (request tracking ID)
+expressHandler automatically sets these headers:
+- `X-Powered-By: @jaypie/express` (always set, overrides Express default)
+- `X-Project-Handler: {name}` (when name option is provided)
+- `X-Project-Invocation: {uuid}` (request tracking ID, always set)
+- `X-Project-Environment: {env}` (when PROJECT_ENV is set)
+- `X-Project-Key: {key}` (when PROJECT_KEY is set)
+- `X-Project-Version: {version}` (when PROJECT_VERSION is set or version option provided)
 
 ## Datadog Integration
 

package/prompts/Jaypie_Init_Express_on_Lambda.md

@@ -1,68 +1,78 @@
 ---
 trigger: model_decision
-description: When asked to create a new workspace or subpackage for express, usually packages/express, to run as serverless Lambdas behind API Gateway
+description: Create a new Express application subpackage that runs as a serverless Lambda behind API Gateway using @jaypie/express utilities
 ---
 
-# Jaypie Initialize Express on Lambda Subpackage
+# Jaypie Initialize Express Application on Lambda
+
+Create an Express application subpackage that uses @jaypie/express to run as a serverless Lambda behind API Gateway. This prompt is for creating **application packages** (like packages/api or packages/backend), not the @jaypie/express library itself.
 
 ## Process
 
 1. Follow Jaypie_Init_Project_Subpackage.md:
-   * Use @project-org/express in packages/express
+   * Choose an appropriate package name (e.g., @project-org/api, @project-org/backend)
+   * Use packages/<package-name> for the directory (e.g., packages/api)
    * This creates the basic subpackage structure with package.json, tsconfig.json, and vitest config files
 
-2. Copy Express-specific template files:
-   * Copy `prompts/templates/express-subpackage/index.ts` to `packages/express/index.ts`
-   * Copy `prompts/templates/express-subpackage/src/app.ts` to `packages/express/src/app.ts`
-   * Copy `prompts/templates/express-subpackage/src/handler.config.ts` to `packages/express/src/handler.config.ts`
-   * Copy `prompts/templates/express-subpackage/src/routes/resource.router.ts` to `packages/express/src/routes/resource.router.ts`
-   * Copy `prompts/templates/express-subpackage/src/routes/resource/resourceGet.route.ts` to `packages/express/src/routes/resource/resourceGet.route.ts`
-   * Copy `prompts/templates/express-subpackage/src/routes/resource/__tests__/resourceGet.route.spec.ts` to `packages/express/src/routes/resource/__tests__/resourceGet.route.spec.ts`
-   * Copy `prompts/templates/express-subpackage/src/types/express.ts` to `packages/express/src/types/express.ts`
+2. Create Express application files using Templates_Express_Subpackage.md:
+   * Create `packages/<package-name>/index.ts` using the index.ts template
+   * Create `packages/<package-name>/src/app.ts` using the app.ts template
+   * Create `packages/<package-name>/src/handler.config.ts` using the handler.config.ts template
+   * Create `packages/<package-name>/src/routes/resource.router.ts` using the resource.router.ts template
+   * Create `packages/<package-name>/src/routes/resource/resourceGet.route.ts` using the resourceGet.route.ts template
+   * Create `packages/<package-name>/src/routes/resource/__tests__/resourceGet.route.spec.ts` using the test template
+   * Create `packages/<package-name>/src/types/express.ts` using the express types template
+   * All templates are documented in Templates_Express_Subpackage.md
 
 3. Update package.json scripts:
-   * Modify the existing scripts section to include:
+   * Add these scripts to the package.json:
      * `"dev": "tsx watch index.ts"`
      * `"start": "node dist/index.js"`
      * `"build": "tsc"`
-   * Run `npm run format:package`
+   * Keep existing scripts from the template (test, lint, typecheck, format)
+   * Run `npm --workspace ./packages/<package-name> run format:package`
 
 4. Install dependencies:
-   * `npm --workspace ./packages/express install jaypie express @codegenie/serverless-express`
-   * `npm --workspace ./packages/express install --save-dev @types/express @types/cors`
-   * Always run `npm install`, never update package.json with dependencies from memory
+   * `npm --workspace ./packages/<package-name> install jaypie express @codegenie/serverless-express`
+   * `npm --workspace ./packages/<package-name> install --save-dev @types/express @types/cors tsx`
+   * Always use npm install commands; never manually edit package.json dependencies
 
 5. Update TypeScript configuration:
-   * Update packages/express/tsconfig.json to include index.ts in the include array: `"include": ["src/**/*", "index.ts"]`
+   * Edit packages/<package-name>/tsconfig.json to include index.ts in the include array
+   * Change include to: `"include": ["src/**/*", "index.ts"]`
    * Change exclude to: `"exclude": ["node_modules", "dist", "**/*.spec.ts"]`
-   * Test the build
-   * Ensure dist/ is in gitignore
+   * Test the build with `npm --workspace ./packages/<package-name> run build`
+   * Verify dist/ is in root .gitignore (it should already be there)
 
 6. Update the top-level package.json:
-   * Add `"dev:express": "npm --workspace packages/express run dev"` and `"start:express": "npm --workspace packages/express run start"`
-   * If there is no stand-alone `dev` or `start`, create a `dev` running `dev:express` and `start` running `start:express`
-   * If `dev` or `start` exist, add calls to express if it fits the goal of the current commands
+   * Add workspace-specific dev and start scripts
+   * Add `"dev:<package-name>": "npm --workspace packages/<package-name> run dev"`
+   * Add `"start:<package-name>": "npm --workspace packages/<package-name> run start"`
+   * If there is no standalone `dev` or `start` script, create them referencing the new package
+   * If `dev` or `start` scripts already exist, consider whether to update them based on project needs
 
 ## Pattern
 
 - TypeScript with ES modules (`"type": "module"`)
 - Handler pattern: configuration → lifecycle → processing → response
-- Optional `handlerConfig` for shared configuration and lifecycle management
-- Clean separation of concerns with middleware patterns
-- Lambda-optimized Express configuration
+- Use `handlerConfig` helper for shared configuration and lifecycle management
+- Separation of concerns: routers, route handlers, and middleware
+- Lambda-optimized Express configuration using @codegenie/serverless-express
+- Development mode: Express listens on port 8080 when NODE_ENV=development
 
 ## Structure
 
 ```
-express/
+<package-name>/
 ├── package.json
 ├── tsconfig.json
-├── vitest.config.ts
-├── vitest.setup.ts
-├── index.ts
+├── vite.config.ts           # From template
+├── vitest.config.ts         # From template
+├── vitest.setup.ts          # From template
+├── index.ts                 # Lambda handler entry point
 ├── src/
-│   ├── app.ts
-│   ├── handler.config.ts
+│   ├── app.ts              # Express app configuration
+│   ├── handler.config.ts   # Shared handler configuration helper
 │   ├── routes/
 │   │   ├── resource.router.ts
 │   │   └── resource/
@@ -70,18 +80,36 @@ express/
 │   │       └── __tests__/
 │   │           └── resourceGet.route.spec.ts
 │   └── types/
-│       └── express.ts
-└── dist/
+│       └── express.ts      # Express type augmentation for req.locals
+└── dist/                   # Generated by tsc
 ```
 
 ## Local Development
 
-### Listening on Port 8080
+The index.ts template checks `process.env.NODE_ENV === "development"` to enable local development mode. In this mode, Express listens on port 8080 (port 3000 is typically reserved for frontend applications).
+
+Start local development with:
+```bash
+npm run dev:<package-name>
+```
 
-A local entrypoint, usually index.ts, may check `process.env.NODE_ENV === "development"` and be allowed to listen on port 8080 (preserving 3000 for front ends).
-`npm run dev:express` should be configured to initialize this mode locally.
+This runs `tsx watch index.ts`, which:
+- Sets up the Express app
+- Listens on port 8080
+- Auto-reloads on file changes
+- Does not invoke serverless-express wrapper
 
 ## Version Compatibility
 
-Jaypie uses Express 4.
-There is no immediately planned upgrade to Express 5.
+- Express: 4.x (Express 5 upgrade not planned)
+- Node: ES modules with TypeScript
+- @codegenie/serverless-express: 4.x
+- @types/express: Compatible with Express 4.x
+
+## Context Files
+
+Reference these files for additional guidance:
+- `Jaypie_Init_Project_Subpackage.md` - Subpackage initialization process
+- `Templates_Express_Subpackage.md` - Code templates for all files
+- `Jaypie_Express_Package.md` - Documentation on @jaypie/express features
+- `Jaypie_Core_Errors_and_Logging.md` - Error handling patterns