@jaypie/mcp 0.7.4 → 0.7.7

package/skills/monorepo.md

@@ -0,0 +1,166 @@
+---
+description: Initialize a Jaypie monorepo project
+related: subpackage, cicd, style, tests
+---
+
+# Jaypie Monorepo Setup
+
+Initialize a new monorepo using Jaypie conventions and utilities.
+
+## Overview
+
+- ESLint 9+ flat config with @jaypie/eslint
+- NPM with Workspaces ("monorepo")
+- TypeScript with ESM modules
+- Vite for building, Vitest for testing
+- Node.js 22, 24, 25 support
+
+## Process
+
+1. Create root configuration files
+2. Install dev dependencies
+3. Configure workspaces
+
+## Root Files
+
+### package.json
+
+```json
+{
+  "name": "@project-org/monorepo",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces --if-present",
+    "clean": "rimraf ./packages/*/dist",
+    "format": "npm run format:package && npm run format:lint",
+    "format:lint": "eslint --fix .",
+    "format:package": "sort-package-json ./package.json ./packages/*/package.json",
+    "lint": "eslint --quiet .",
+    "test": "vitest run",
+    "typecheck": "npm run typecheck --workspaces --if-present"
+  }
+}
+```
+
+### eslint.config.mjs
+
+```javascript
+export { default } from "@jaypie/eslint";
+```
+
+For projects needing custom rules:
+
+```javascript
+import jaypie from "@jaypie/eslint";
+
+export default [
+  ...jaypie,
+  {
+    ignores: ["LOCAL/**"],
+  },
+];
+```
+
+### tsconfig.json (root)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### vitest.workspace.ts
+
+```typescript
+export default ["packages/*/vitest.config.{ts,js}"];
+```
+
+### .gitignore
+
+```
+.DS_Store
+node_modules
+dist
+
+# Local env files
+.env
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+
+# Editor directories
+.idea
+*.sw?
+
+# Build artifacts
+*.tsbuildinfo
+```
+
+### .vscode/settings.json
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "typescript.preferences.importModuleSpecifier": "relative"
+}
+```
+
+## Installation
+
+Install root dev dependencies:
+
+```bash
+npm install --save-dev @jaypie/eslint @jaypie/testkit eslint rimraf sort-package-json tsx vite vite-plugin-dts vitest
+```
+
+## Workspace Conventions
+
+| Directory | Purpose |
+|-----------|---------|
+| `packages/` | npm packages (default workspace) |
+| `stacks/` | CDK-deployed infrastructure and sites |
+
+## Scripts Reference
+
+| Script | Top-level | Package-level |
+|--------|-----------|---------------|
+| `build` | `npm run build --workspaces` | `vite build` |
+| `clean` | `rimraf ./packages/*/dist` | `rimraf dist` |
+| `format` | `eslint --fix .` | `eslint --fix` |
+| `format:package` | `sort-package-json ./package.json ./packages/*/package.json` | `sort-package-json` |
+| `lint` | `eslint --quiet .` | `eslint` |
+| `test` | `vitest run` | `vitest run` |
+| `typecheck` | `npm run typecheck --workspaces` | `tsc --noEmit` |
+
+## Guidelines
+
+- Run `npm install` to generate package-lock.json (do not hard-code versions)
+- Use `"version": "0.0.1"`, `"type": "module"`, and `"private": true` for new packages
+- Do not include authors, keywords, or external links in package.json
+- If this is the first commit, commit directly to main; otherwise create a branch
+
+## Next Steps
+
+- `skill("subpackage")` - Create packages within the monorepo
+- `skill("cicd")` - Add GitHub Actions workflows
+- `skill("tests")` - Testing patterns with Vitest

package/skills/secrets.md

@@ -5,190 +5,188 @@ related: aws, cdk, variables
 
 # Secret Management
 
-Jaypie uses AWS Secrets Manager for secure credential storage, with environment-aware resolution that works seamlessly in both local development and Lambda.
+Jaypie uses AWS Secrets Manager for secure credential storage. The `JaypieEnvSecret` construct creates secrets at deploy time from environment variables, and `getEnvSecret` retrieves them at runtime.
 
-## Basic Usage
+## The Pattern
 
-Use `getEnvSecret` for environment-aware secret resolution:
+1. **Deploy time**: Set environment variables in CI/CD (e.g., `MONGODB_URI=mongodb+srv://...`)
+2. **CDK**: `JaypieEnvSecret` reads the env var and creates/updates an AWS secret
+3. **Runtime**: `getEnvSecret("MONGODB_URI")` fetches from Secrets Manager
+
+This keeps secrets out of code and config files while enabling environment-specific values.
+
+## CDK: Creating Secrets with JaypieEnvSecret
+
+The simplest pattern uses the environment variable name as the construct ID:
 
 ```typescript
-import { getEnvSecret } from "jaypie";
+import { JaypieEnvSecret, JaypieLambda } from "@jaypie/constructs";
 
-const apiKey = await getEnvSecret("ANTHROPIC_API_KEY");
-const dbUri = await getEnvSecret("MONGODB_URI");
+// Creates secret from process.env.MONGODB_URI at deploy time
+const mongoSecret = new JaypieEnvSecret(this, "MONGODB_URI");
+const anthropicSecret = new JaypieEnvSecret(this, "ANTHROPIC_API_KEY");
+
+// Lambda with secrets array (auto-creates JaypieEnvSecret instances)
+new JaypieLambda(this, "Handler", {
+  code: "dist/lambda",
+  handler: "index.handler",
+  secrets: ["MONGODB_URI", "ANTHROPIC_API_KEY"],
+});
 ```
 
-### How getEnvSecret Works
+When the construct ID matches an environment variable name, `JaypieEnvSecret` automatically:
+- Uses that env var's value as the secret content
+- Sets `envKey` to the ID for later reference
 
-`getEnvSecret` checks environment variables in order:
+### CI/CD Setup
 
-1. `SECRET_{name}` - If found, fetches from AWS Secrets Manager
-2. `{name}_SECRET` - If found, fetches from AWS Secrets Manager
-3. `{name}` - Returns direct value without AWS call
+Set secrets as environment variables in your deployment pipeline:
 
-This allows the same code to work locally (with direct env values) and in Lambda (with secret references).
+```yaml
+# GitHub Actions example
+jobs:
+  deploy:
+    env:
+      MONGODB_URI: ${{ secrets.MONGODB_URI }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    steps:
+      - run: npx cdk deploy
+```
 
-## Loading Multiple Secrets
+## Runtime: Retrieving Secrets
 
-Use `loadEnvSecrets` during handler initialization:
+Use `getEnvSecret` to fetch secrets in Lambda:
 
 ```typescript
-import { loadEnvSecrets } from "jaypie";
-
-// Load secrets and set in process.env
-await loadEnvSecrets("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "MONGODB_URI");
+import { getEnvSecret } from "jaypie";
 
-// Now available as process.env.ANTHROPIC_API_KEY, etc.
+const mongoUri = await getEnvSecret("MONGODB_URI");
+const apiKey = await getEnvSecret("ANTHROPIC_API_KEY");
 ```
 
-## CDK Configuration
+### Loading Multiple Secrets
 
-Reference secrets via environment variables in CDK:
+Use `loadEnvSecrets` during handler initialization to populate `process.env`:
 
 ```typescript
-const handler = new JaypieLambda(this, "Handler", {
-  environment: {
-    // SECRET_ prefix triggers AWS Secrets Manager fetch
-    SECRET_MONGODB_URI: "my-project/mongodb-uri",
-    SECRET_API_KEY: "my-project/third-party-api-key",
-  },
-});
-```
+import { loadEnvSecrets } from "jaypie";
 
-In code:
+await loadEnvSecrets("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "MONGODB_URI");
 
-```typescript
-// getEnvSecret sees SECRET_MONGODB_URI and fetches from Secrets Manager
-const mongoUri = await getEnvSecret("MONGODB_URI");
+// Now available as process.env.ANTHROPIC_API_KEY, etc.
 ```
 
-## Direct Secret Access
+## Provider/Consumer Pattern
 
-Use `getSecret` when you need to fetch by exact AWS secret name:
+For shared secrets across environments (e.g., sandbox providing to personal builds):
 
 ```typescript
-import { getSecret } from "jaypie";
+// Sandbox stack (provider) - exports the secret name
+new JaypieEnvSecret(this, "SHARED_API_KEY", { provider: true });
 
-// Fetch by exact AWS secret name
-const secret = await getSecret("my-project/production/api-key");
+// Personal build (consumer) - imports from sandbox
+new JaypieEnvSecret(this, "SHARED_API_KEY"); // consumer auto-detected
 ```
 
-Note: `getSecret` requires `AWS_SESSION_TOKEN` and always calls Secrets Manager. Prefer `getEnvSecret` for typical use cases.
+The construct auto-detects consumer mode for personal/ephemeral environments (`PROJECT_ENV=personal` or `CDK_ENV_PERSONAL=true`).
 
-## Creating Secrets
+## Generated Secrets
 
-### Via CDK
+For secrets without a source value (e.g., database passwords):
 
 ```typescript
-import { Secret } from "aws-cdk-lib/aws-secretsmanager";
-
-const secret = new Secret(this, "ApiKey", {
-  secretName: `${projectKey}/api-key`,
-  description: "Third-party API key",
+new JaypieEnvSecret(this, "DB_PASSWORD", {
+  generateSecretString: {
+    excludePunctuation: true,
+    passwordLength: 32,
+  },
 });
-
-// Grant read access
-secret.grantRead(lambdaFunction);
 ```
 
-### Via AWS CLI
+## Tagging
 
-```bash
-aws secretsmanager create-secret \
-  --name "my-project/api-key" \
-  --secret-string "sk_live_abc123"
+Apply standard tags for organization:
+
+```typescript
+new JaypieEnvSecret(this, "STRIPE_KEY", {
+  roleTag: CDK.ROLE.PAYMENT,
+  vendorTag: CDK.VENDOR.STRIPE,
+});
 ```
 
-## Secret Naming Convention
+## Local Development
 
-Use project-prefixed names:
+For local development, set environment variables directly in `.env.local`:
 
+```bash
+# .env.local (not committed)
+ANTHROPIC_API_KEY=sk-ant-test123
+MONGODB_URI=mongodb://localhost:27017/dev
 ```
-{project-key}/{secret-name}
 
-Examples:
-- my-api/mongodb-uri
-- my-api/stripe-key
-- my-api/auth0-secret
-```
+`getEnvSecret` returns these values directly without AWS calls when no `SECRET_` prefix is present.
 
-## JSON Secrets
+## Alternative Approaches
 
-Store structured data:
+### Explicit Value
 
-```bash
-aws secretsmanager create-secret \
-  --name "my-project/db-credentials" \
-  --secret-string '{"username":"admin","password":"secret123"}'
+Pass a value directly instead of reading from environment:
+
+```typescript
+new JaypieEnvSecret(this, "ApiKey", {
+  value: "sk_live_abc123", // Not recommended - prefer env vars
+});
 ```
 
-Retrieve in code:
+### Manual SECRET_ Linking
+
+For non-JaypieEnvSecret secrets, manually set the `SECRET_` prefix:
 
 ```typescript
-const credentialsJson = await getEnvSecret("DB_CREDENTIALS");
-const credentials = JSON.parse(credentialsJson);
+new JaypieLambda(this, "Handler", {
+  environment: {
+    SECRET_MONGODB_URI: "my-project/mongodb-uri", // AWS secret name
+  },
+});
 ```
 
-## Caching
+At runtime, `getEnvSecret("MONGODB_URI")` sees `SECRET_MONGODB_URI` and fetches from that AWS secret name.
 
-Secrets are cached by default to reduce API calls:
+The `_SECRET` suffix also works:
 
 ```typescript
-// First call: fetches from Secrets Manager
-const key1 = await getEnvSecret("API_KEY");
-
-// Second call: returns cached value
-const key2 = await getEnvSecret("API_KEY");
+environment: {
+  MONGODB_URI_SECRET: "my-project/mongodb-uri",
+}
 ```
 
-Cache is scoped to Lambda execution context (warm starts reuse cache).
+### Direct Secret Access
 
-## Rotation
-
-Configure automatic rotation for supported secrets:
+Use `getSecret` when you need to fetch by exact AWS secret name:
 
 ```typescript
-const secret = new Secret(this, "DbPassword", {
-  secretName: "my-project/db-password",
-  generateSecretString: {
-    excludePunctuation: true,
-    passwordLength: 32,
-  },
-});
+import { getSecret } from "jaypie";
 
-secret.addRotationSchedule("Rotation", {
-  automaticallyAfter: Duration.days(30),
-  rotationLambda: rotationFunction,
-});
+const secret = await getSecret("my-project/production/api-key");
 ```
 
-## Local Development
-
-For local development, set environment variables directly:
+Note: `getSecret` requires `AWS_SESSION_TOKEN` and always calls Secrets Manager.
 
-```bash
-# .env.local (not committed)
-ANTHROPIC_API_KEY=sk-ant-test123
-MONGODB_URI=mongodb://localhost:27017/dev
-API_KEY=test_key_123
-```
+## Caching
 
-`getEnvSecret` automatically returns these values without AWS calls since there's no `SECRET_` prefix.
+Secrets are cached by default to reduce API calls. Cache is scoped to Lambda execution context (warm starts reuse cache).
 
 ## IAM Permissions
 
-Lambda needs `secretsmanager:GetSecretValue`:
+`JaypieEnvSecret` implements `ISecret`, so grant access directly:
 
 ```typescript
+const secret = new JaypieEnvSecret(this, "API_KEY");
 secret.grantRead(lambdaFunction);
-
-// Or via policy
-lambdaFunction.addToRolePolicy(new PolicyStatement({
-  actions: ["secretsmanager:GetSecretValue"],
-  resources: [secret.secretArn],
-}));
 ```
 
+Or use the `secrets` array on `JaypieLambda`, which handles permissions automatically.
+
 ## Testing
 
 Mock secret functions in tests:

package/skills/skills.md

@@ -16,7 +16,7 @@ Look up skills by alias: `mcp__jaypie__skill(alias)`
 | Category | Skills |
 |----------|--------|
 | contents | index, releasenotes |
-| development | documentation, errors, logs, mocks, style, tests |
-| infrastructure | aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, secrets, variables |
+| development | documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests |
+| infrastructure | aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, secrets, streaming, variables, websockets |
 | patterns | fabric, handlers, models, services, vocabulary |
 | meta | issues, jaypie, skills, tools |

package/skills/subpackage.md

@@ -0,0 +1,219 @@
+---
+description: Create a subpackage within a monorepo
+related: monorepo, tests, style
+---
+
+# Jaypie Subpackage Setup
+
+Create a new subpackage within an existing Jaypie monorepo.
+
+## Overview
+
+- TypeScript subpackage with Vite/Vitest
+- Standard Jaypie project structure
+- NPM workspace integration
+- ESLint configuration inheritance
+
+## Guidelines
+
+- Subpackage names follow `@project-org/package-name` pattern
+- Use `"version": "0.0.1"`, `"type": "module"`, and `"private": true`
+- Place packages in `packages/<package-name>/` directory
+- Use Vite for new TypeScript packages
+- Never manually edit package.json for dependencies; use npm commands
+
+## Process
+
+1. Create package directory structure
+2. Create configuration files from templates
+3. Create basic src structure
+4. Update workspace configuration
+5. Install dependencies
+
+## Directory Structure
+
+```
+packages/<package-name>/
+├── src/
+│   ├── index.ts
+│   └── __tests__/
+│       └── index.spec.ts
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+├── vitest.config.ts
+└── vitest.setup.ts
+```
+
+## Template Files
+
+### package.json
+
+```json
+{
+  "name": "@project-org/package-name",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "vite build",
+    "clean": "rimraf dist",
+    "format": "eslint --fix",
+    "format:package": "sort-package-json",
+    "lint": "eslint",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "exclude": ["node_modules", "dist"],
+  "include": ["src/**/*"]
+}
+```
+
+### vite.config.ts
+
+```typescript
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+  plugins: [
+    dts({
+      include: ["src"],
+      exclude: ["**/*.spec.ts"],
+    }),
+  ],
+  build: {
+    lib: {
+      entry: "./src/index.ts",
+      name: "PackageName",
+      fileName: "index",
+      formats: ["es"],
+    },
+    rollupOptions: {
+      external: [
+        // Add external dependencies here
+        "jaypie",
+      ],
+    },
+    target: "node22",
+  },
+});
+```
+
+### vitest.config.ts
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+### vitest.setup.ts
+
+```typescript
+import { matchers as jaypieMatchers } from "@jaypie/testkit";
+import * as extendedMatchers from "jest-extended";
+import { expect } from "vitest";
+
+expect.extend(extendedMatchers);
+expect.extend(jaypieMatchers);
+```
+
+### src/index.ts
+
+```typescript
+// Export public API here
+export {};
+```
+
+### src/__tests__/index.spec.ts
+
+```typescript
+import { describe, expect, it } from "vitest";
+
+describe("Package Name", () => {
+  describe("Base Cases", () => {
+    it("is a function", () => {
+      // Replace with actual export test
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("Happy Paths", () => {
+    it("works", () => {
+      // Add happy path tests
+      expect(true).toBe(true);
+    });
+  });
+});
+```
+
+## Installation Commands
+
+Add dependencies to the subpackage:
+
+```bash
+# Runtime dependencies
+npm install <package-name> --workspace ./packages/<package-name>
+
+# Dev dependencies
+npm install <package-name> --workspace ./packages/<package-name> --save-dev
+```
+
+Common dev dependencies for subpackages:
+
+```bash
+npm install jest-extended --workspace ./packages/<package-name> --save-dev
+```
+
+## Workspace Configuration
+
+The root `vitest.workspace.ts` uses a glob pattern that auto-discovers packages:
+
+```typescript
+export default ["packages/*/vitest.config.{ts,js}"];
+```
+
+New packages are automatically included when they have a `vitest.config.ts`.
+
+## Checklist
+
+After creating a subpackage:
+
+1. ✅ Update package name in `package.json`
+2. ✅ Update `name` in `vite.config.ts` build.lib
+3. ✅ Add external dependencies to `rollupOptions.external`
+4. ✅ Run `npm install` from root to link workspace
+5. ✅ Verify with `npm run build -w packages/<package-name>`
+6. ✅ Verify with `npm run test -w packages/<package-name>`
+
+## Next Steps
+
+- `skill("tests")` - Testing patterns with Vitest
+- `skill("mocks")` - Mock patterns via @jaypie/testkit
+- `skill("style")` - Code style conventions