@jaypie/mcp 0.3.2 → 0.4.0

package/prompts/Jaypie_CICD_with_GitHub_Actions.md

@@ -1,371 +0,0 @@
----
-description: conventions around deployment and environment variables, especially CDK_ENV_ and PROJECT_
----
-
-# Jaypie CI/CD with GitHub Actions
-
-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:
-
-| Environment | Purpose |
-|-------------|---------|
-| production | Live environment, standalone |
-| development | Validates multi-environment deployment works |
-| sandbox | Shared testing environment |
-| personal | Developer-specific builds tied to GitHub actor |
-
-## Naming Conventions
-
-### 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.
-
-## File Structure
-
-Workflow files follow this order:
-
-```yaml
-name:
-on:
-concurrency:
-env:         # alphabetical
-jobs:        # alphabetical
-```
-
-### Style Rules
-
-1. Do not use secrets in the `env` section
-2. Only pass secrets as environment variables to tasks that require them
-3. Declare programmatic variables in `env` with empty string and comment:
-   ```yaml
-   env:
-     PROJECT_VERSION: ""  # Set from package.json during build
-   ```
-4. Static variables should be set in `env`, not in job steps
-
-## Triggers
-
-| Environment | Trigger |
-|-------------|---------|
-| 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 |
-|-------------|----------------------|
-| production | Required to pass before deploy |
-| development | Required to pass before deploy |
-| sandbox | Runs in parallel with deploy |
-| personal | Runs in parallel with deploy |
-
-### Linting and Testing
-
-Use `npm run lint` and `npm run test`. Verify the test script uses `vitest run` or otherwise does not watch. If the script watches, propose changing it or use `vitest run` directly.
-
-## Concurrency
-
-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
-```
-
-### Stack Builds
-
-```yaml
-concurrency:
-  group: deploy-stack-documentation-${{ github.event.inputs.environment || 'development' }}
-```
-
-### Personal Builds
-
-```yaml
-concurrency:
-  group: deploy-personal-build-${{ github.actor }}
-```
-
-## Personal Builds
-
-Personal builds allow developers to create isolated deployments connected to shared resources. They use the sandbox environment but with a unique `PROJECT_ENV` value.
-
-### Configuration
-
-Set `PROJECT_ENV` to a unique value per developer:
-
-```yaml
-- name: Setup Environment
-  uses: ./.github/actions/setup-environment
-  with:
-    project-env: ${{ github.actor }}
-```
-
-### Branch Naming
-
-Personal builds trigger on branches not matching static environments:
-- `feat/*` branches deploy personal builds
-- `nobuild-*` and `nobuild/*` branches skip deployment
-
-## GitHub Environments
-
-Create GitHub environments matching deployment targets:
-- `development`
-- `production`
-- `sandbox`
-
-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
-
-Application variables may be prefixed with `APP_`. Build systems and frontend frameworks may require their own prefixes (e.g., `NUXT_`, `VITE_`).
-
-### CDK Variables
-
-Environment-specific variables for CDK use the `CDK_ENV_` prefix.
-
-| Variable | Source | Example |
-|----------|--------|---------|
-| `CDK_ENV_API_HOSTED_ZONE` | Workflow | Route53 hosted zone for API |
-| `CDK_ENV_API_SUBDOMAIN` | Workflow | API subdomain |
-| `CDK_ENV_REPO` | Workflow | GitHub repository |
-| `CDK_ENV_WEB_HOSTED_ZONE` | Workflow | Route53 hosted zone for web |
-| `CDK_ENV_WEB_SUBDOMAIN` | Workflow | Web subdomain |
-| `CDK_ENV_BUCKET` | Stack | S3 bucket name |
-| `CDK_ENV_QUEUE_URL` | Stack | SQS queue URL |
-| `CDK_ENV_SNS_ROLE_ARN` | Stack | SNS role ARN |
-| `CDK_ENV_SNS_TOPIC_ARN` | Stack | SNS topic ARN |
-
-### Jaypie Variables
-
-Variables for Jaypie and the application use the `PROJECT_` prefix.
-
-| Variable | Description | Example Values |
-|----------|-------------|----------------|
-| `PROJECT_ENV` | Environment identifier | `development`, `production`, `sandbox`, or GitHub actor |
-| `PROJECT_KEY` | Project shortname/slug | `myapp` |
-| `PROJECT_NONCE` | Eight-character random string | `860b5a0f` |
-| `PROJECT_SERVICE` | Service name | `myapp` |
-| `PROJECT_SPONSOR` | Project sponsor/organization | `finlaysonstudio` |
-
-### Log Levels
-
-| Variable | Default |
-|----------|---------|
-| `LOG_LEVEL` | `debug` |
-| `MODULE_LOG_LEVEL` | `warn` |
-
-### Vendor Variables
-
-Follow naming from vendor documentation. If documentation does not reference environment variables, use the vendor name prefix (e.g., `E2B_TEAM_ID`, `POSTMAN_ENVIRONMENT_UUID`).
-
-## 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:
-- `SECRET_MONGODB_URI` - Secret name in AWS Secrets Manager
-- `MONGODB_URI` - Direct value (for local development)
-
-### Passing Secrets
-
-Secrets are passed to CDK via `JaypieEnvSecret` construct and made available at runtime.
-
-Pass secrets only to steps that need them:
-
-```yaml
-- name: Deploy CDK Stack
-  uses: ./.github/actions/cdk-deploy
-  with:
-    stack-name: AppStack
-  env:
-    SECRET_API_KEY: ${{ secrets.API_KEY }}
-```
-
-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`:
-
-```typescript
-// bin/cdk.ts
-new AppStack(app, "AppStack");  // "AppStack" is the stack ID
-```
-
-```yaml
-# deploy-env-*.yml
-- name: Deploy CDK Stack
-  uses: ./.github/actions/cdk-deploy
-  with:
-    stack-name: AppStack  # Must match the stack ID above
-```
-
-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
-
-Use OIDC authentication with `aws-actions/configure-aws-credentials@v4`:
-
-```yaml
-permissions:
-  id-token: write
-  contents: read
-
-steps:
-  - name: Configure AWS Credentials
-    uses: aws-actions/configure-aws-credentials@v4
-    with:
-      role-to-assume: ${{ vars.AWS_ROLE_ARN }}
-      role-session-name: DeployRoleForGitHubSession
-      aws-region: us-east-1
-```
-
-Create an IAM role with trust policy for GitHub OIDC provider. Scope the trust policy to your repository.
-
-### Datadog
-
-Integrate Datadog for observability by storing the API key in AWS Secrets Manager:
-
-```yaml
-env:
-  CDK_ENV_DATADOG_API_KEY_ARN: ${{ vars.DATADOG_API_KEY_ARN }}
-```
-
-The CDK stack retrieves the key at deploy time and configures Lambda instrumentation.
-

package/prompts/Jaypie_Commander_CLI_Package.md

@@ -1,166 +0,0 @@
----
-description: setup for commander-based CLI packages
----
-
-# Jaypie Commander CLI Package
-
-Create a CLI subpackage with commander.js for command-line applications
-
-## Goal
-
-* TypeScript CLI application with command-line interface
-* Commander.js integration for argument parsing
-* Standard Jaypie project structure and npm workspace integration
-* Version support and hello command implementation
-
-## Guidelines
-
-* Follow Jaypie_Init_Project_Subpackage conventions for monorepo setup
-* Package name follows "@parent-namespace/cli" or "parent-repo-cli" based on top-level package.json naming
-* Use commander.js for CLI functionality
-* Include executable script configuration
-* Default package name: `packages/cli`
-* Default script name: `run`
-
-## Process
-
-1. Follow Jaypie_Init_Project_Subpackage to create basic subpackage structure
-
-2. Install commander.js and dotenv:
-   ```bash
-   npm --workspace ./packages/cli install commander dotenv
-   npm --workspace ./packages/cli install --save-dev @types/node
-   ```
-
-3. Create CLI entry point `src/index.ts`:
-   ```typescript
-   import dotenv from 'dotenv';
-   import { Command } from 'commander';
-   import { version } from '../package.json';
-   import { registerCommands } from './commands/index.js';
-
-   dotenv.config();
-
-   const program = new Command();
-
-   program
-     .version(version)
-     .description('CLI application');
-
-   registerCommands(program);
-
-   program.parse();
-   ```
-
-4. Create command registrar `src/commands/index.ts`:
-   ```typescript
-   import { Command } from "commander";
-   import { helloCommand } from "./hello.js";
-
-   export function registerCommands(program: Command): Command {
-     helloCommand(program);
-     
-     return program;
-   }
-   ```
-
-5. Create example command `src/commands/hello.ts`:
-   ```typescript
-   import { Command } from "commander";
-
-   export function helloCommand(program: Command): Command {
-     program
-       .command("hello")
-       .description("Say hello to the specified name")
-       .argument('[name]', 'name to greet', 'World')
-       .argument('[salutation]', 'greeting word', 'Hello')
-       .action((name: string, salutation: string) => {
-         console.log(`${salutation}, ${name}!`);
-       });
-       
-     return program;
-   }
-   ```
-
-6. Create test file `src/commands/hello.spec.ts`:
-   ```typescript
-   import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-   import { Command } from 'commander';
-   import { helloCommand } from './hello.js';
-
-   describe('helloCommand', () => {
-     let consoleSpy: any;
-
-     beforeEach(() => {
-       consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-     });
-
-     afterEach(() => {
-       consoleSpy.mockRestore();
-     });
-
-     it('should register hello command', () => {
-       const program = new Command();
-       helloCommand(program);
-       
-       const command = program.commands.find(cmd => cmd.name() === 'hello');
-       expect(command).toBeDefined();
-       expect(command?.description()).toBe('Say hello to the specified name');
-     });
-
-     it('should use default values with no arguments', () => {
-       const program = new Command();
-       helloCommand(program);
-       
-       program.parse(['node', 'test', 'hello']);
-       
-       expect(consoleSpy).toHaveBeenCalledWith('Hello, World!');
-     });
-
-     it('should use custom name with one argument', () => {
-       const program = new Command();
-       helloCommand(program);
-       
-       program.parse(['node', 'test', 'hello', 'Alice']);
-       
-       expect(consoleSpy).toHaveBeenCalledWith('Hello, Alice!');
-     });
-
-     it('should use custom name and salutation with two arguments', () => {
-       const program = new Command();
-       helloCommand(program);
-       
-       program.parse(['node', 'test', 'hello', 'Bob', 'Hi']);
-       
-       expect(consoleSpy).toHaveBeenCalledWith('Hi, Bob!');
-     });
-   });
-   ```
-
-7. Create executable script `bin/run`:
-   ```bash
-   #!/usr/bin/env node
-   require('../dist/index.js');
-   ```
-
-8. Update package.json configuration:
-   * Add `"bin": { "run": "./bin/run" }`
-   * Add `"scripts": { "start": "node ./bin/run" }`
-   * Include `"resolveJsonModule": true` in tsconfig.json compilerOptions
-
-9. Create bin directory and make script executable:
-   ```bash
-   mkdir packages/cli/bin
-   chmod +x packages/cli/bin/run
-   ```
-
-10. Build and test:
-    ```bash
-    npm run build --workspace packages/cli
-    npm start --workspace packages/cli -- hello "Mr. Bond" Goodbye
-    ```
-
-## Context
-
-context/prompts/Jaypie_Init_Project_Subpackage.md
-context/prompts/Jaypie_Project_Structure.md

package/prompts/Jaypie_Core_Errors_and_Logging.md

@@ -1,39 +0,0 @@
----
-description: error and logging philosophy
----
-
-# Jaypie Core Errors and Logging
-
-Execution of most Jaypie apps comes through an event "handler" function implementing jaypieHandler, most often expressHandler or lambdaHandler.
-
-## Errors
-
-Jaypie providers errors that will be handled properly when thrown (e.g., presenting the correct status code).
-
-`import { BadGatewayError, BadRequestError, ConfigurationError, ForbiddenError, GatewayTimeoutError, GoneError, IllogicalError, InternalError, MethodNotAllowedError, NotFoundError, NotImplementedError, RejectedError, TeapotError, UnauthorizedError, UnavailableError, UnhandledError, UnreachableCodeError } from "jaypie";`
-
-ConfigurationError is a special InternalError 500 that is can be thrown for incorrect types and other "developer" errors.
-
-Though supported, rely on default error messages when throwing.
-Custom error messages should be logged.
-
-<Bad>
-throw new NotFoundError("Item not found");
-</Bad>
-<Good>
-log.error("Item not found");
-throw new NotFoundError();
-</Good>
-
-Error messages may be returned to the user especially in express.
-
-## Logging
-
-`import { log } from "jaypie";`
-
-`log` has methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `var`.
-Only `trace` and `var` should be used in "happy paths".
-`debug` should be used when execution deviates from the happy path.
-`info` should rarely be used.
-`var` expects a _single_ key-value pair like `log.var({ key: "value" });`.
-Do _not_ pass multiple keys to `var`.