@jaypie/mcp 0.3.2 → 0.4.0

package/skills/models.md

@@ -0,0 +1,195 @@
+---
+description: Data models and type definitions
+related: fabric, dynamodb, services
+---
+
+# Data Models
+
+Patterns for defining data models and types in Jaypie applications.
+
+## TypeScript Interfaces
+
+### Basic Model
+
+```typescript
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  role: "user" | "admin";
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### Input/Output Types
+
+Separate types for different operations:
+
+```typescript
+// Create input - required fields only
+export interface UserCreateInput {
+  email: string;
+  name: string;
+  role?: "user" | "admin";
+}
+
+// Update input - all optional
+export interface UserUpdateInput {
+  name?: string;
+  role?: "user" | "admin";
+}
+
+// Response type - full model
+export interface UserResponse extends User {
+  // Additional computed fields
+  displayName: string;
+}
+```
+
+## Fabric Service Models
+
+Define input schemas inline with fabric services:
+
+```typescript
+import { fabricService } from "@jaypie/fabric";
+
+const createUser = fabricService({
+  alias: "user_create",
+  description: "Create a new user",
+  input: {
+    email: {
+      type: String,
+      required: true,
+      description: "User email address",
+    },
+    name: {
+      type: String,
+      required: true,
+      description: "User display name",
+    },
+    role: {
+      type: ["user", "admin"] as const,
+      required: false,
+      description: "User role (defaults to user)",
+    },
+  },
+  service: async ({ email, name, role }) => {
+    // Input is validated and typed
+    return createUserInDatabase({ email, name, role: role || "user" });
+  },
+});
+```
+
+## Validation Patterns
+
+### Zod Schemas
+
+```typescript
+import { z } from "zod";
+
+export const userSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(["user", "admin"]).default("user"),
+});
+
+export type User = z.infer<typeof userSchema>;
+
+// Validate input
+const validated = userSchema.parse(input);
+```
+
+### Custom Validators
+
+```typescript
+const emailValidator = (email: string): boolean => {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+};
+
+const service = fabricService({
+  alias: "user_create",
+  input: {
+    email: { type: String, required: true },
+  },
+  service: async ({ email }) => {
+    if (!emailValidator(email)) {
+      throw new BadRequestError("Invalid email format");
+    }
+    // ...
+  },
+});
+```
+
+## DynamoDB Models
+
+See `skill("dynamodb")` for DynamoDB-specific patterns.
+
+```typescript
+// Single-table design types
+export interface DynamoItem {
+  pk: string;  // Partition key
+  sk: string;  // Sort key
+  type: string;
+  data: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+  ttl?: number;
+}
+
+export interface UserItem extends DynamoItem {
+  type: "USER";
+  data: {
+    email: string;
+    name: string;
+    role: "user" | "admin";
+  };
+}
+```
+
+## API Response Models
+
+```typescript
+// Standard response wrapper
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+// Paginated response
+export interface PaginatedResponse<T> {
+  items: T[];
+  nextToken?: string;
+  total?: number;
+}
+```
+
+## Best Practices
+
+1. **Export types** - Make types available for consumers
+2. **Separate concerns** - Input, output, and storage types differ
+3. **Use const assertions** - `as const` for literal types
+4. **Document fields** - Add JSDoc comments for complex types
+5. **Prefer interfaces** - Use `interface` over `type` for objects
+
+## Type Documentation
+
+```typescript
+/**
+ * Represents a user in the system.
+ * @property id - Unique identifier (UUID)
+ * @property email - Validated email address
+ * @property role - Access level for permissions
+ */
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  role: "user" | "admin";
+}
+```
+

package/skills/releasenotes.md

@@ -0,0 +1,94 @@
+---
+description: Version history and release notes
+---
+
+# Release Notes
+
+How to access and write release notes for Jaypie packages.
+
+## MCP Tools
+
+```
+mcp__jaypie__list_release_notes()
+mcp__jaypie__list_release_notes(package: "mcp")
+mcp__jaypie__list_release_notes(package: "jaypie", since_version: "1.0.0")
+mcp__jaypie__read_release_note(package: "mcp", version: "0.3.4")
+```
+
+## Directory Structure
+
+```
+packages/mcp/release-notes/
+├── jaypie/
+│   └── 1.2.3.md
+├── mcp/
+│   └── 0.3.4.md
+└── testkit/
+    └── 2.0.0.md
+```
+
+## File Format
+
+Create `release-notes/<package>/<version>.md`:
+
+```yaml
+---
+version: 0.3.4
+date: 2025-01-20
+summary: Brief one-line summary for listing
+---
+
+## Changes
+
+### New Features
+
+- Feature description
+
+### Bug Fixes
+
+- Fix description
+
+### Breaking Changes
+
+- Breaking change description
+```
+
+## When to Add
+
+Add release notes when:
+- Bumping package version (required)
+- Merging significant features
+- Making breaking changes
+- Fixing notable bugs
+
+## Writing Guidelines
+
+1. **Summary** - One line, present tense, describes the release
+2. **Changes** - Group by type: New Features, Bug Fixes, Breaking Changes
+3. **Bullets** - Start with verb (Add, Fix, Update, Remove)
+4. **Links** - Reference issues/PRs when relevant
+
+## Example
+
+```markdown
+---
+version: 1.2.0
+date: 2025-01-15
+summary: Add streaming support for LLM providers
+---
+
+## Changes
+
+### New Features
+
+- Add streaming response support for Anthropic and OpenAI
+- Add `onChunk` callback for real-time token processing
+
+### Bug Fixes
+
+- Fix timeout handling in concurrent requests
+
+### Breaking Changes
+
+- Remove deprecated `legacyMode` option
+```

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);
+  });
+});
+```
+