@jaypie/mcp 0.1.9 → 0.2.0

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

@@ -0,0 +1,408 @@
+---
+description: Complete guide to using Jaypie Express features including expressHandler, CORS, lifecycle hooks, and pre-built routes
+globs: packages/express/**
+---
+
+# Jaypie Express Package
+
+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
+
+```bash
+npm install jaypie
+# or
+npm install @jaypie/express
+```
+
+## expressHandler
+
+Wraps Express route handlers with error handling, logging, and lifecycle management.
+
+### Basic Usage
+
+```typescript
+import { expressHandler } from "jaypie";
+import type { Request, Response } from "express";
+
+const myRoute = expressHandler(async (req: Request, res: Response) => {
+  return { message: "Hello, World!" };
+});
+
+// Use in Express
+app.get("/hello", myRoute);
+```
+
+### Return Value Handling
+
+expressHandler automatically formats responses based on return values:
+
+| Return Value | HTTP Status | Response |
+|--------------|-------------|----------|
+| Object | 200 | JSON body |
+| 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
+import { expressHandler } from "jaypie";
+import type { ExpressHandlerOptions } from "jaypie";
+
+const options: ExpressHandlerOptions = {
+  name: "myHandler",        // Handler name for logging
+  chaos: "low",             // Chaos testing level
+  unavailable: false,       // Return 503 if true
+  setup: [],                // Setup function(s)
+  teardown: [],             // Teardown function(s)
+  validate: [],             // Validation function(s)
+  locals: {},               // Values to set on req.locals
+};
+
+const handler = expressHandler(async (req, res) => {
+  return { success: true };
+}, options);
+
+// Alternative: options first
+const handler2 = expressHandler(options, async (req, res) => {
+  return { success: true };
+});
+```
+
+## 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 validation and the main handler. Use for initialization, authentication checks, or setting up request context.
+
+```typescript
+import { expressHandler } from "jaypie";
+import type { JaypieHandlerSetup } from "jaypie";
+
+const authenticateUser: JaypieHandlerSetup = async (req, res) => {
+  const token = req.headers.authorization;
+  // Validate token, throw UnauthorizedError if invalid
+};
+
+const loadTenant: JaypieHandlerSetup = async (req, res) => {
+  req.locals.tenant = await getTenant(req.params.tenantId);
+};
+
+const handler = expressHandler(
+  async (req, res) => {
+    // req.locals.tenant is available here
+    return { tenant: req.locals.tenant };
+  },
+  {
+    setup: [authenticateUser, loadTenant],
+  }
+);
+```
+
+### Teardown Functions
+
+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";
+
+const closeConnection: JaypieHandlerTeardown = async (req, res) => {
+  await req.locals.dbConnection?.close();
+};
+
+const handler = expressHandler(
+  async (req, res) => {
+    req.locals.dbConnection = await openConnection();
+    return await doWork(req.locals.dbConnection);
+  },
+  {
+    teardown: closeConnection,
+  }
+);
+```
+
+### Validation Functions
+
+Run before the main handler. Return `true` to continue or `false`/throw to reject.
+
+```typescript
+import { ForbiddenError } from "jaypie";
+import type { JaypieHandlerValidate } from "jaypie";
+
+const requireAdmin: JaypieHandlerValidate = (req, res) => {
+  if (!req.locals.user?.isAdmin) {
+    throw new ForbiddenError();
+  }
+  return true;
+};
+
+const validateBody: JaypieHandlerValidate = (req, res) => {
+  return req.body?.email && req.body?.name;
+};
+
+const handler = expressHandler(
+  async (req, res) => {
+    // Only runs if user is admin and body is valid
+    return { success: true };
+  },
+  {
+    validate: [requireAdmin, validateBody],
+  }
+);
+```
+
+### Locals
+
+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";
+
+const getUser: ExpressHandlerLocals = async (req, res) => {
+  return await User.findById(req.params.userId);
+};
+
+const handler = expressHandler(
+  async (req, res) => {
+    // Access via req.locals
+    console.log(req.locals.apiVersion); // "v1"
+    console.log(req.locals.user);       // User object
+    return req.locals.user;
+  },
+  {
+    locals: {
+      apiVersion: "v1",          // Static value
+      user: getUser,             // Function called after setup
+    },
+  }
+);
+```
+
+## CORS Helper
+
+Configures CORS middleware using the `cors` npm package with automatic origin validation.
+
+```typescript
+import { cors } from "jaypie";
+import type { CorsConfig } from "jaypie";
+
+// Default: uses BASE_URL or PROJECT_BASE_URL env vars
+app.use(cors());
+
+// Wildcard origin
+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",
+  overrides: {
+    // Additional options passed to the cors package
+    credentials: true,
+  },
+};
+app.use(cors(corsConfig));
+```
+
+Environment variables:
+- `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
+
+Ready-to-use route handlers for common responses.
+
+```typescript
+import {
+  badRequestRoute,       // 400 Bad Request
+  echoRoute,             // 200 with request echo
+  forbiddenRoute,        // 403 Forbidden
+  goneRoute,             // 410 Gone
+  methodNotAllowedRoute, // 405 Method Not Allowed
+  noContentRoute,        // 204 No Content
+  notFoundRoute,         // 404 Not Found
+  notImplementedRoute,   // 501 Not Implemented
+} from "jaypie";
+
+// Use as catch-all or placeholder routes
+app.all("/deprecated/*", goneRoute);
+app.use("*", notFoundRoute);
+
+// Echo route for debugging
+app.get("/debug/echo", echoRoute);
+```
+
+## HTTP Code Handler
+
+Create custom HTTP status code handlers.
+
+```typescript
+import { expressHttpCodeHandler, HTTP } from "jaypie";
+
+// Returns 200 OK with empty body
+const okRoute = expressHttpCodeHandler(HTTP.CODE.OK);
+
+// Returns 202 Accepted
+const acceptedRoute = expressHttpCodeHandler(202, { name: "accepted" });
+
+app.post("/jobs", acceptedRoute);
+```
+
+## Error Handling
+
+Throw Jaypie errors for proper HTTP responses.
+
+```typescript
+import {
+  expressHandler,
+  BadRequestError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  InternalError,
+  log,
+} from "jaypie";
+
+const handler = expressHandler(async (req, res) => {
+  const item = await findItem(req.params.id);
+
+  if (!item) {
+    log.warn("Item not found");
+    throw new NotFoundError();
+  }
+
+  if (!canAccess(req.user, item)) {
+    throw new ForbiddenError();
+  }
+
+  return item;
+});
+```
+
+Errors return JSON:API compliant error responses:
+
+```json
+{
+  "errors": [{
+    "status": 404,
+    "title": "Not Found",
+    "detail": "The requested resource was not found"
+  }]
+}
+```
+
+## TypeScript Types
+
+All lifecycle function types are exported for type safety:
+
+```typescript
+import type {
+  ExpressHandlerOptions,
+  ExpressHandlerLocals,
+  JaypieHandlerSetup,
+  JaypieHandlerTeardown,
+  JaypieHandlerValidate,
+  CorsConfig,
+} from "jaypie";
+```
+
+## Complete Example
+
+```typescript
+import express from "express";
+import {
+  cors,
+  expressHandler,
+  notFoundRoute,
+  NotFoundError,
+  ForbiddenError,
+  UnauthorizedError,
+  log,
+} from "jaypie";
+import type {
+  JaypieHandlerSetup,
+  JaypieHandlerValidate,
+  ExpressHandlerLocals,
+} from "jaypie";
+
+const app = express();
+app.use(express.json());
+app.use(cors());
+
+// Lifecycle functions
+const authenticate: JaypieHandlerSetup = async (req, res) => {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+  if (!token) throw new UnauthorizedError();
+  req.locals.user = await verifyToken(token);
+};
+
+const requireOwner: JaypieHandlerValidate = (req, res) => {
+  return req.locals.resource?.ownerId === req.locals.user?.id;
+};
+
+const loadResource: ExpressHandlerLocals = async (req, res) => {
+  const resource = await Resource.findById(req.params.id);
+  if (!resource) throw new NotFoundError();
+  return resource;
+};
+
+// Route handler
+const updateResource = expressHandler(
+  async (req, res) => {
+    const { resource, user } = req.locals;
+
+    resource.name = req.body.name;
+    resource.updatedBy = user.id;
+    await resource.save();
+
+    log.trace("Resource updated");
+    return resource;
+  },
+  {
+    name: "updateResource",
+    setup: authenticate,
+    validate: requireOwner,
+    locals: {
+      resource: loadResource,
+    },
+  }
+);
+
+app.put("/resources/:id", updateResource);
+app.use("*", notFoundRoute);
+
+export default app;
+```
+
+## Response Headers
+
+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
+
+When Datadog environment variables are configured, expressHandler automatically submits metrics for each request including status code and path.