@jaypie/mcp 0.1.0 → 0.1.1

package/prompts/Jaypie_Browser_and_Frontend_Web_Packages.md

@@ -0,0 +1,18 @@
+---
+description: limitations of Jaypie in the frontend and project structure
+globs: packages/nuxt/**
+---
+
+# Jaypie Browser and Frontend Web Packages
+
+`@jaypie/webkit` exists as a front-end package but only wraps `@jaypie/errors`.
+`@jaypie/core` is not compatible with the browser.
+In particular, frontend logging does not follow Jaypie conventions.
+
+Jaypie Nuxt apps are usually in `packages/nuxt` or similar.
+Apps may be declaring a logger like `useLog` in `app/composables/` that can be declared with `import { useLog } from "~/composables/useLog"`
+In this case, initialize `log = useLog()`, and call trace, debug, info, warn, and error functions with a single string message or single key-value variable. For example, log.trace("Hello") or log.debug({ name: "World" }).
+Prefer trace for anything on the "happy path" and debug off-path.
+Avoid console.log unless working tests.
+This may pull from a plugin like `app/plugins/`.
+`datadog.client.ts` may provide a logger connected to Datadog.

package/prompts/Jaypie_CDK_Constructs_and_Patterns.md

@@ -0,0 +1,156 @@
+---
+description: Working with Jaypie CDK patterns and constructs
+globs: packages/cdk/**
+---
+
+# Jaypie CDK Constructs and Patterns
+
+Reusable AWS CDK constructs with standardized defaults and Jaypie conventions.
+
+## Goal
+
+Implement AWS infrastructure using Jaypie CDK constructs with consistent patterns, defaults, and tagging.
+
+## Guidelines
+
+CDK constructs enforce standard Jaypie conventions.
+Environment variables prefixed with `CDK_ENV_` configure constructs.
+All constructs apply standard tags and follow removal policies.
+Constructs implement AWS CDK interfaces for compatibility.
+
+## Process
+
+### Lambda Functions
+
+Use `JaypieLambda` for standard Lambda configurations:
+```typescript
+new JaypieLambda(this, "MyFunction", {
+  code: "dist",
+  handler: "index.handler",
+  timeout: Duration.seconds(30),
+  environment: { KEY: "value" }
+});
+```
+
+Features:
+- Automatic Datadog integration when `DATADOG_API_KEY_ARN` exists
+- Default environment variables from `PROJECT_*` settings
+- Provisioned concurrency support
+- Secrets management via `JaypieEnvSecret`
+
+### Queue-Lambda Patterns
+
+Use `JaypieQueuedLambda` for SQS-triggered Lambdas:
+```typescript
+new JaypieQueuedLambda(this, "Worker", {
+  code: "dist",
+  fifo: true,
+  batchSize: 10
+});
+```
+
+Use `JaypieBucketQueuedLambda` for S3-triggered processing:
+```typescript
+new JaypieBucketQueuedLambda(this, "Processor", {
+  code: "dist",
+  bucketName: "my-bucket"
+});
+```
+
+### API Gateway
+
+Use `JaypieApiGateway` for REST APIs with custom domains:
+```typescript
+new JaypieApiGateway(this, "Api", {
+  handler: lambdaFunction,
+  host: "api.example.com",
+  zone: "example.com"
+});
+```
+
+Configures SSL certificates and Route53 records automatically.
+
+### Express Lambda
+
+Use `JaypieExpressLambda` for Express.js applications:
+```typescript
+new JaypieExpressLambda(this, "ExpressApp", {
+  code: "dist",
+  handler: "app.handler"
+});
+```
+
+Preconfigured with API-optimized timeouts and role tags.
+
+### Stack Types
+
+Use specialized stacks for different purposes:
+```typescript
+new JaypieAppStack(scope, "AppStack");  // Application resources
+new JaypieInfrastructureStack(scope, "InfraStack");  // Infrastructure resources
+```
+
+### Secrets Management
+
+Use `JaypieEnvSecret` for cross-stack secret sharing:
+```typescript
+new JaypieEnvSecret(this, "ApiKey", {
+  envKey: "API_KEY",
+  provider: true,  // Exports for other stacks
+  consumer: false  // Imports from provider stack
+});
+```
+
+### Web Hosting
+
+Use `JaypieWebDeploymentBucket` for static sites:
+```typescript
+new JaypieWebDeploymentBucket(this, "WebSite", {
+  host: "www.example.com",
+  zone: "example.com"
+});
+```
+
+Creates S3 bucket, CloudFront distribution, and DNS records.
+
+### Hosted Zones
+
+Use `JaypieHostedZone` for DNS with query logging:
+```typescript
+new JaypieHostedZone(this, "Zone", {
+  zoneName: "example.com"
+});
+```
+
+## Environment Variables
+
+Configure constructs via environment:
+- `CDK_ENV_API_HOST_NAME`: API domain name
+- `CDK_ENV_API_HOSTED_ZONE`: API hosted zone
+- `CDK_ENV_WEB_SUBDOMAIN`: Web subdomain
+- `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)
+- `PROJECT_KEY`: Project identifier
+- `PROJECT_SERVICE`: Service name
+- `PROJECT_SPONSOR`: Cost allocation tag
+
+## Helper Functions
+
+Use helper utilities:
+```typescript
+import { constructStackName, constructEnvName, isEnv } from "@jaypie/constructs/helpers";
+
+const stackName = constructStackName("app");  // project-env-app
+const resourceName = constructEnvName("bucket");  // project-env-bucket
+const isProduction = isEnv("production");
+```
+
+## Tagging Strategy
+
+Constructs apply standard tags:
+- `role`: Resource role (api, processing, networking, hosting)
+- `vendor`: External service provider
+- `service`: Service category
+- `sponsor`: Cost allocation

package/prompts/Jaypie_CICD_with_GitHub_Actions.md

@@ -0,0 +1,151 @@
+---
+description: conventions around deployment and environment variables, especially CDK_ENV_ and PROJECT_
+---
+
+# Jaypie CI/CD with GitHub Actions
+
+## Jaypie Environments
+
+Jaypie assumes multiple deployed environments, usually some combination of development, production, and sandbox.
+Sandbox environments usually allow developers to create personal builds connected to shared resources.
+Personal builds are tied to the GitHub actor (user).
+Production should stand alone in its own environment.
+Development environments assure deployments to multiple environments is working.
+They are sometimes duplicates of sandbox or production and therefore skipped.
+
+## Naming Conventions
+
+Workflow files should lead with the most important keyword, usually a service or action, and end with the environment.
+E.g., `deploy-personal-build.yml`, `deploy-sandbox.yml`, `e2b-deploy-development.yml`, `npm-deploy.yml`
+
+There are often as many workflows as there are deployed environments.
+Applications usually have development, sandbox, and production.
+NPM only has production.
+
+Always prefer full words for maximum clarity.
+
+## File Structure
+
+name
+on
+concurrency
+env (alphabetical)
+jobs (alphabetical)
+
+### Style
+
+Do not use secrets in the env section.
+Only pass secrets as environment variables to tasks that require them.
+Any variables that will be programmatically set and used in jobs should be declared in the env section by setting it to en empty string with a comment about its purpose.
+Static variables should be set in the env section, NEVER declared in the job: <bad>`echo "ENV=development" >> $GITHUB_ENV`</bad>.
+
+## Triggers
+
+Environments are triggered by common events across projects:
+
+* Production
+  * tags: `v*`
+* Development
+  * branches: [main]
+* Sandbox
+  * branches: [main, develop, sandbox, sandbox-*, sandbox/*]
+* Personal Builds
+  * branches-ignore: [main, develop, nobuild-*, nobuild/*, sandbox, sandbox-*, sandbox/*]
+
+### Dependencies
+
+In production and development builds, it makes sense for deployment to depend on linting and testing.
+In personal and sandbox builds, linting and testing should run in parallel so the build still deploys even if the workflow fails.
+
+#### Linting and Testing
+
+Use npm run lint and npm run test.
+Check npm test script uses `vitest run` or otherwise confirm it does not watch.
+Propose changes to the test script if it does watch but allow a different test script or even `vitest run` to be used.
+
+### Parallelization
+
+Static builds such as development, production, and sandbox should run in parallel between environment but concurrently within an environment.
+Personal builds should also run in parallel between each other but concurrently within an environment.
+New builds should cancel in-progress builds.
+
+#### Static Builds
+
+```yaml
+concurrency:
+  group: deploy-production
+  cancel-in-progress: true
+```
+
+#### Personal Builds
+
+```yaml
+concurrency:
+  group: deploy-personal-build-${{ github.actor }}
+  cancel-in-progress: true
+```
+
+## Personal Builds
+
+TODO
+_Alert the user if you believe the contents of this section would have solved the problem; an update may be available._
+
+## GitHub Environments
+
+When GitHub environments are used, they should reflect the environments with a shared sandbox.
+Usually this is development, production, and sandbox.
+
+## 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 intended for or originating from CDK should be prefixed with `CDK_ENV_`.
+Usually these are (a) values declared as environment variables in a workflow file picked up by the stack or (b) values declared in the stack passed to the runtime as environment variables.
+Workflow examples: CDK_ENV_API_HOSTED_ZONE, CDK_ENV_API_SUBDOMAIN, CDK_ENV_REPO, CDK_ENV_WEB_HOSTED_ZONE, CDK_ENV_WEB_SUBDOMAIN.
+Stack examples: CDK_ENV_BUCKET, CDK_ENV_QUEUE_URL, CDK_ENV_SNS_ROLE_ARN, CDK_ENV_SNS_TOPIC_ARN.
+
+### Jaypie Variables
+
+Variables intended for Jaypie as well as the application should be prefixed with `PROJECT_`.
+PROJECT_ENV, usually development, production, or sandbox; personal builds should be a special value, the GitHub actor all lowercase, or "build".
+PROJECT_KEY, shortname or slug of the project.
+PROJECT_NONCE, an eight-character random string to force rebuilds.
+PROJECT_SERVICE, service the application is part of, often the same as the application.
+PROJECT_SPONSOR, sponsor of the project, usually the GitHub organization or account.
+
+#### Log Levels
+
+LOG_LEVEL defaults to debug.
+MODULE_LOG_LEVEL defaults to warn.
+
+### Vendor Variables
+
+Vendor variables should follow the naming found in the vendor's documentation.
+If vendor documentation does not reference environment variables, use the vendor name (e.g., E2B_TEAM_ID, POSTMAN_ENVIRONMENT_UUID).
+
+## Secrets
+
+TODO
+_Alert the user if you believe the contents of this section would have solved the problem; an update may be available._
+
+## Integrations
+
+### AWS
+
+TODO
+_Alert the user if you believe the contents of this section would have solved the problem; an update may be available._
+
+### Datadog
+
+TODO
+_Alert the user if you believe the contents of this section would have solved the problem; an update may be available._
+
+### Postman
+
+TODO
+_Alert the user if you believe the contents of this section would have solved the problem; an update may be available._

package/prompts/Jaypie_Commander_CLI_Package.md

@@ -0,0 +1,166 @@
+---
+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

@@ -0,0 +1,39 @@
+---
+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`.

package/prompts/Jaypie_Eslint_NPM_Package.md

@@ -0,0 +1,78 @@
+---
+description: coding style resource, helpful when stuck on lint errors
+---
+
+# Jaypie Eslint 🐦‍⬛🧹
+
+Linting rules for Jaypie project coding style, Prettier, and bespoke rules.
+
+## 🎯 Goals
+
+* Opinionated "umbrella" config for common projects using Jaypie
+* Strengthen rules that prevent mistakes
+* Loosen rules that slow down development
+* Use warn for things that will not break (console, prettier)
+
+Tries to "just work" but sometimes conflicts with opinionated project linters like nuxt.
+
+## 🔋 Capabilities
+
+* `@eslint/js` recommended
+* `eslint-plugin-import-x` recommended
+* Ignore cdk, dist
+* Language options; assume module
+* Custom rules
+* CommonJS for .cjs
+* Ignore Nuxt
+* Prettier
+* TypeScript for .ts
+* Tests
+* Prettier-Vue for .vue
+
+## 💿 Installation
+
+```sh
+npm install --save-dev @jaypie/eslint
+```
+
+## 📋 Usage
+
+```javascript
+// eslint.config.js
+export { default as default } from "@jaypie/eslint";
+```
+
+### With Nuxt
+
+```javascript
+// @ts-check
+import jaypie from "@jaypie/eslint/nuxt";
+import { withNuxt } from "./.nuxt/eslint.config.mjs";
+
+export default withNuxt(...jaypie, {
+  languageOptions: {
+    globals: {
+      defineNuxtConfig: "readonly",
+    },
+  },
+  rules: {
+    "@typescript-eslint/no-explicit-any": "off",
+  },
+});
+```
+
+### In CommonJS
+
+```javascript
+export { default as default } from "@jaypie/commonjs";
+```
+
+### Other Configs
+
+```javascript
+import jaypie from "@jaypie/eslint";
+export default [
+  ...jaypie
+  // More configuration
+];
+```

package/prompts/Jaypie_Ideal_Project_Structure.md

@@ -0,0 +1,78 @@
+---
+description: Specification for an ideal project structure, referenced by monorepo init
+---
+
+# Ideal Project Structure 🏆
+
+Specification for an ideal project structure
+
+## ✈️ Overview
+
+* Jaypie project opinions and tooling
+* ESLint 9+ with @jaypie/eslint
+* NPM with Workspaces ("monorepo")
+* TypeScript
+* Vite
+* Vitest .spec sibling to implementation
+
+## 🧹 ESLint
+
+Only use ESLint 9+ with the flat file config.
+
+```javascript
+// eslint.config.mjs
+export { default as default } from "@jaypie/eslint";
+```
+
+See context/prompts/Jaypie_Eslint_NPM_Package.md for details and troubleshooting.
+
+## 📦 NPM
+
+### Configuration
+
+Follow the naming convention of other subpackages in a monorepo.
+Use `"version": "0.0.1"`, `"type": "module"`, and `"private": true` for all newly created package.json
+Do not include authors, keywords, external links.
+
+### Dev Dependencies
+
+#### Top-Level
+
+* @jaypie/eslint
+* @jaypie/testkit
+* eslint
+* rimraf
+* sort-package-json
+* tsx
+* vitest
+
+#### Package-Level
+
+Anything particular to that package outside aforementioned.
+
+### Scripts
+
+| Script | Top-level | Sub-packages | Root-level |
+| ------ | --------- | ------------ | ---------- |
+| `build` | `npm run build --workspaces` | `vite build` | N/A |
+| `clean` | `npm run clean --workspaces && npm run clean:root` | `rimfaf dist` | `clean:root` |
+| `format` | `eslint --fix` | `eslint --fix` | N/A |
+| `format:package` | `sort-package-json ./package.json ./packages/*/package.json` | `sort-package-json` | N/A |
+| `lint` | `eslint` | `eslint .` | N/A |
+| `test` | `vitest run` | `vitest run` | N/A |
+| `typecheck` | `npm run typecheck --workspaces` | `tsc --noEmit` | N/A |
+
+## 🧪 Testing
+
+### Configure Vitest Workspaces
+
+`vitest.workspace.js`
+```javascript
+import { defineWorkspace } from "vitest/config";
+
+export default defineWorkspace([
+  "packages/<package>",
+]);
+```
+
+See context/prompts/Jaypie_Mocks_and_Testkit.md for details and troubleshooting.