@jaypie/mcp 0.3.2 → 0.3.4

package/skills/secrets.md

@@ -0,0 +1,155 @@
+---
+description: Secret management with AWS Secrets Manager
+related: aws, cdk, variables
+---
+
+# Secret Management
+
+Jaypie uses AWS Secrets Manager for secure credential storage.
+
+## Basic Usage
+
+```typescript
+import { getSecret } from "jaypie";
+
+const apiKey = await getSecret("my-api-key");
+const dbUri = await getSecret("mongodb-connection-string");
+```
+
+## Environment Variables
+
+Reference secrets via environment variables in CDK:
+
+```typescript
+const handler = new JaypieLambda(this, "Handler", {
+  environment: {
+    SECRET_MONGODB_URI: "mongodb-connection-string",
+    SECRET_API_KEY: "third-party-api-key",
+  },
+});
+```
+
+In code:
+
+```typescript
+const secretName = process.env.SECRET_MONGODB_URI;
+const mongoUri = await getSecret(secretName);
+```
+
+## Creating Secrets
+
+### Via CDK
+
+```typescript
+import { Secret } from "aws-cdk-lib/aws-secretsmanager";
+
+const secret = new Secret(this, "ApiKey", {
+  secretName: `${projectKey}/api-key`,
+  description: "Third-party API key",
+});
+
+// Grant read access
+secret.grantRead(lambdaFunction);
+```
+
+### Via AWS CLI
+
+```bash
+aws secretsmanager create-secret \
+  --name "my-project/api-key" \
+  --secret-string "sk_live_abc123"
+```
+
+## Secret Naming Convention
+
+Use project-prefixed names:
+
+```
+{project-key}/{secret-name}
+
+Examples:
+- my-api/mongodb-uri
+- my-api/stripe-key
+- my-api/auth0-secret
+```
+
+## JSON Secrets
+
+Store structured data:
+
+```bash
+aws secretsmanager create-secret \
+  --name "my-project/db-credentials" \
+  --secret-string '{"username":"admin","password":"secret123"}'
+```
+
+Retrieve in code:
+
+```typescript
+const credentialsJson = await getSecret("my-project/db-credentials");
+const credentials = JSON.parse(credentialsJson);
+```
+
+## Caching
+
+Secrets are cached by default to reduce API calls:
+
+```typescript
+// First call: fetches from Secrets Manager
+const key1 = await getSecret("api-key");
+
+// Second call: returns cached value
+const key2 = await getSecret("api-key");
+```
+
+Cache is scoped to Lambda execution context (warm starts reuse cache).
+
+## Rotation
+
+Configure automatic rotation for supported secrets:
+
+```typescript
+const secret = new Secret(this, "DbPassword", {
+  secretName: "my-project/db-password",
+  generateSecretString: {
+    excludePunctuation: true,
+    passwordLength: 32,
+  },
+});
+
+secret.addRotationSchedule("Rotation", {
+  automaticallyAfter: Duration.days(30),
+  rotationLambda: rotationFunction,
+});
+```
+
+## Local Development
+
+For local development, use environment variables:
+
+```bash
+# .env.local (not committed)
+MONGODB_URI=mongodb://localhost:27017/dev
+API_KEY=test_key_123
+```
+
+In code, check for direct value first:
+
+```typescript
+const mongoUri = process.env.MONGODB_URI || await getSecret(process.env.SECRET_MONGODB_URI);
+```
+
+## IAM Permissions
+
+Lambda needs `secretsmanager:GetSecretValue`:
+
+```typescript
+secret.grantRead(lambdaFunction);
+
+// Or via policy
+lambdaFunction.addToRolePolicy(new PolicyStatement({
+  actions: ["secretsmanager:GetSecretValue"],
+  resources: [secret.secretArn],
+}));
+```
+

package/skills/services.md

@@ -0,0 +1,175 @@
+---
+description: Service layer patterns and architecture
+related: fabric, models, tests
+---
+
+# Service Layer Patterns
+
+Organizing business logic in Jaypie applications.
+
+## Service Structure
+
+Keep business logic in service modules:
+
+```
+src/
+├── handlers/         # Lambda/Express handlers
+├── services/         # Business logic
+│   ├── user.ts
+│   └── order.ts
+├── models/           # Data models
+└── utils/            # Utilities
+```
+
+## Basic Service Pattern
+
+```typescript
+// services/user.ts
+import { log, NotFoundError, BadRequestError } from "jaypie";
+import { User } from "../models/user.js";
+
+export async function getUser(userId: string) {
+  log.debug("Getting user", { userId });
+
+  const user = await User.findById(userId);
+  if (!user) {
+    throw new NotFoundError(`User ${userId} not found`);
+  }
+
+  return user;
+}
+
+export async function createUser(input: UserCreateInput) {
+  log.info("Creating user", { email: input.email });
+
+  const existing = await User.findOne({ email: input.email });
+  if (existing) {
+    throw new BadRequestError("Email already registered");
+  }
+
+  return User.create(input);
+}
+```
+
+## Handler Integration
+
+Handlers call services:
+
+```typescript
+// handlers/user.ts
+import { lambdaHandler } from "@jaypie/lambda";
+import { getUser, createUser } from "../services/user.js";
+
+export const getUserHandler = lambdaHandler(async (event) => {
+  const { userId } = event.pathParameters;
+  return getUser(userId);
+});
+
+export const createUserHandler = lambdaHandler(async (event) => {
+  const input = JSON.parse(event.body);
+  return createUser(input);
+});
+```
+
+## Service Dependencies
+
+Inject dependencies for testability:
+
+```typescript
+// services/notification.ts
+import { log } from "jaypie";
+
+export interface NotificationService {
+  sendEmail(to: string, subject: string, body: string): Promise<void>;
+  sendSms(to: string, message: string): Promise<void>;
+}
+
+export function createNotificationService(
+  emailClient: EmailClient,
+  smsClient: SmsClient
+): NotificationService {
+  return {
+    async sendEmail(to, subject, body) {
+      log.info("Sending email", { to, subject });
+      await emailClient.send({ to, subject, body });
+    },
+    async sendSms(to, message) {
+      log.info("Sending SMS", { to });
+      await smsClient.send({ to, message });
+    },
+  };
+}
+```
+
+## Transaction Patterns
+
+For DynamoDB operations that must succeed together, use TransactWriteItems:
+
+```typescript
+import { TransactWriteItemsCommand } from "@aws-sdk/client-dynamodb";
+
+export async function transferFunds(fromId: string, toId: string, amount: number) {
+  const from = await getAccount(fromId);
+
+  if (from.balance < amount) {
+    throw new BadRequestError("Insufficient funds");
+  }
+
+  const command = new TransactWriteItemsCommand({
+    TransactItems: [
+      {
+        Update: {
+          TableName: TABLE_NAME,
+          Key: { pk: { S: `ACCOUNT#${fromId}` }, sk: { S: "BALANCE" } },
+          UpdateExpression: "SET balance = balance - :amount",
+          ExpressionAttributeValues: { ":amount": { N: String(amount) } },
+        },
+      },
+      {
+        Update: {
+          TableName: TABLE_NAME,
+          Key: { pk: { S: `ACCOUNT#${toId}` }, sk: { S: "BALANCE" } },
+          UpdateExpression: "SET balance = balance + :amount",
+          ExpressionAttributeValues: { ":amount": { N: String(amount) } },
+        },
+      },
+    ],
+  });
+
+  await dynamoClient.send(command);
+  log.info("Transfer completed", { fromId, toId, amount });
+}
+```
+
+## Service Testing
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getUser } from "./user.js";
+import { User } from "../models/user.js";
+
+vi.mock("../models/user.js");
+
+describe("getUser", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns user when found", async () => {
+    const mockUser = { id: "123", name: "John" };
+    vi.mocked(User.findById).mockResolvedValue(mockUser);
+
+    const result = await getUser("123");
+
+    expect(result).toEqual(mockUser);
+    expect(User.findById).toHaveBeenCalledWith("123");
+  });
+
+  it("throws NotFoundError when missing", async () => {
+    vi.mocked(User.findById).mockResolvedValue(null);
+
+    await expect(getUser("123")).rejects.toThrow(NotFoundError);
+  });
+});
+```
+

package/skills/style.md

@@ -0,0 +1,190 @@
+---
+description: Code style conventions and patterns
+related: errors, tests
+---
+
+# Code Style
+
+Jaypie coding conventions and patterns.
+
+## General Rules
+
+### TypeScript Everywhere
+
+Use TypeScript for all code:
+
+```typescript
+// GOOD
+function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+
+// BAD
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+### ESM Over CommonJS
+
+Use ES modules:
+
+```typescript
+// GOOD
+import { log } from "jaypie";
+export function myFunction() {}
+
+// BAD
+const { log } = require("jaypie");
+module.exports = { myFunction };
+```
+
+### Alphabetize Everything
+
+Alphabetize imports, object keys, exports:
+
+```typescript
+// GOOD
+import { ConfigurationError, log, NotFoundError } from "jaypie";
+
+const config = {
+  apiKey: "...",
+  baseUrl: "...",
+  timeout: 5000,
+};
+
+// BAD
+import { NotFoundError, log, ConfigurationError } from "jaypie";
+```
+
+## Function Signatures
+
+### Object Parameters
+
+Use destructured objects for multiple parameters:
+
+```typescript
+// GOOD
+function createUser({ email, name, role }: CreateUserInput) {}
+
+// GOOD (single required + optional config)
+function fetchData(url: string, { timeout, retries }: FetchOptions = {}) {}
+
+// BAD (multiple positional parameters)
+function createUser(email: string, name: string, role: string) {}
+```
+
+### Allow Zero Arguments
+
+Functions with optional config should allow no arguments:
+
+```typescript
+// GOOD
+function initialize(options: InitOptions = {}) {
+  const { timeout = 5000, retries = 3 } = options;
+}
+
+// Call with or without args
+initialize();
+initialize({ timeout: 10000 });
+```
+
+## Constants
+
+### File-Level Constants
+
+Use SCREAMING_SNAKE_CASE for constants:
+
+```typescript
+const DEFAULT_TIMEOUT = 5000;
+const DATADOG_SITE = "datadoghq.com";
+const HTTP_STATUS = {
+  OK: 200,
+  NOT_FOUND: 404,
+} as const;
+```
+
+### Magic Numbers
+
+Never use magic numbers inline:
+
+```typescript
+// BAD
+if (retries > 3) { ... }
+await sleep(5000);
+
+// GOOD
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 5000;
+
+if (retries > MAX_RETRIES) { ... }
+await sleep(RETRY_DELAY_MS);
+```
+
+## Error Handling
+
+### Never Vanilla Error
+
+```typescript
+// BAD
+throw new Error("Missing config");
+
+// GOOD
+import { ConfigurationError } from "jaypie";
+throw new ConfigurationError("Missing config");
+```
+
+### Error Context
+
+Include relevant context:
+
+```typescript
+throw new NotFoundError("User not found", {
+  context: { userId, searchedAt: new Date() }
+});
+```
+
+## Avoid Over-Engineering
+
+### No Premature Abstraction
+
+```typescript
+// BAD - Unnecessary abstraction for one use
+const formatName = (name) => name.toUpperCase();
+const processUser = (user) => ({ ...user, name: formatName(user.name) });
+
+// GOOD - Simple and direct
+const processUser = (user) => ({ ...user, name: user.name.toUpperCase() });
+```
+
+### Minimal Changes
+
+Only modify what's requested:
+
+- Bug fix? Fix the bug, nothing else.
+- Add feature? Add only that feature.
+- Don't add docstrings to unchanged code.
+- Don't refactor surrounding code.
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Functions | camelCase | `getUser`, `createOrder` |
+| Classes | PascalCase | `UserService`, `OrderModel` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRIES`, `API_URL` |
+| Files | kebab-case | `user-service.ts`, `order-model.ts` |
+| Types/Interfaces | PascalCase | `UserInput`, `IUserService` |
+
+## Lint Rules
+
+Use `@jaypie/eslint`:
+
+```javascript
+// eslint.config.mjs
+import jaypie from "@jaypie/eslint";
+export default [...jaypie];
+```
+
+Always run `npm run format` before committing.
+

package/skills/tests.md

@@ -0,0 +1,209 @@
+---
+description: Testing patterns with Vitest
+related: mocks, errors
+---
+
+# Testing Patterns
+
+Jaypie uses Vitest for testing with specific patterns and mocks.
+
+## Setup
+
+### vitest.config.ts
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      reporter: ["text", "json", "html"],
+    },
+    globals: true,
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+### vitest.setup.ts
+
+```typescript
+import { vi } from "vitest";
+
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+```
+
+## Test Structure
+
+### File Organization
+
+```
+src/
+├── services/
+│   └── user.ts
+└── __tests__/
+    └── user.spec.ts
+
+# Or co-located:
+src/
+└── services/
+    ├── user.ts
+    └── user.spec.ts
+```
+
+### Test File Pattern
+
+```typescript
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+describe("UserService", () => {
+  describe("getUser", () => {
+    it("returns user when found", async () => {
+      // Arrange
+      const mockUser = { id: "123", name: "John" };
+      vi.mocked(User.findById).mockResolvedValue(mockUser);
+
+      // Act
+      const result = await getUser("123");
+
+      // Assert
+      expect(result).toEqual(mockUser);
+    });
+  });
+});
+```
+
+## Running Tests
+
+```bash
+# Run all tests (non-watch mode)
+npm test
+
+# Run specific package
+npm test -w packages/my-package
+
+# Watch mode (development)
+npx vitest
+
+# With coverage
+npm test -- --coverage
+```
+
+**Important**: Always use `npm test` or `vitest run`, not bare `vitest` which runs in watch mode.
+
+## Mocking
+
+### Module Mocks
+
+```typescript
+vi.mock("./user-service.js", () => ({
+  getUser: vi.fn(),
+  createUser: vi.fn(),
+}));
+
+// Access mocked functions
+import { getUser } from "./user-service.js";
+
+vi.mocked(getUser).mockResolvedValue({ id: "123" });
+```
+
+### Jaypie Mocks
+
+```typescript
+import { log, getSecret } from "jaypie";
+
+it("logs the operation", async () => {
+  await myFunction();
+  expect(log.info).toHaveBeenCalledWith("Operation started");
+});
+
+it("uses secrets", async () => {
+  vi.mocked(getSecret).mockResolvedValue("test-key");
+  await myFunction();
+  expect(getSecret).toHaveBeenCalledWith("api-key");
+});
+```
+
+## Testing Errors
+
+```typescript
+import { NotFoundError } from "jaypie";
+
+it("throws NotFoundError when user missing", async () => {
+  vi.mocked(User.findById).mockResolvedValue(null);
+
+  await expect(getUser("invalid")).rejects.toThrow(NotFoundError);
+});
+
+it("includes error context", async () => {
+  vi.mocked(User.findById).mockResolvedValue(null);
+
+  try {
+    await getUser("invalid");
+    expect.fail("Should have thrown");
+  } catch (error) {
+    expect(error.context.userId).toBe("invalid");
+  }
+});
+```
+
+## Async Testing
+
+```typescript
+it("handles async operations", async () => {
+  const result = await asyncFunction();
+  expect(result).toBeDefined();
+});
+
+it("handles promises", () => {
+  return expect(asyncFunction()).resolves.toBeDefined();
+});
+
+it("handles rejections", () => {
+  return expect(failingFunction()).rejects.toThrow();
+});
+```
+
+## Before/After Hooks
+
+```typescript
+describe("UserService", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  beforeAll(async () => {
+    // One-time setup
+  });
+
+  afterAll(async () => {
+    // One-time cleanup
+  });
+});
+```
+
+## Snapshot Testing
+
+```typescript
+it("renders expected output", () => {
+  const result = buildConfig({ env: "production" });
+  expect(result).toMatchSnapshot();
+});
+```
+
+## Test Coverage
+
+Aim for meaningful coverage, not 100%:
+
+- Test business logic thoroughly
+- Test error paths
+- Skip trivial getters/setters
+- Skip generated code
+