@jaypie/mcp 0.3.1 → 0.3.4

package/skills/legacy.md

@@ -0,0 +1,97 @@
+---
+description: Legacy libraries and deprecated patterns
+related: dynamodb, fabric, mocks
+---
+
+# Legacy Patterns
+
+Deprecated libraries and patterns that may exist in older Jaypie projects.
+
+## @jaypie/core (Deprecated)
+
+Migrated to `@jaypie/kit`. Update imports:
+
+```typescript
+// Old
+import { someUtil } from "@jaypie/core";
+
+// New
+import { someUtil } from "@jaypie/kit";
+```
+
+## @jaypie/mongoose (Legacy)
+
+MongoDB/Mongoose integration. Consider DynamoDB for new projects.
+
+### Connection
+
+```typescript
+import { connectMongoose } from "@jaypie/mongoose";
+
+export const handler = async (event) => {
+  await connectMongoose();
+  // Connection cached for Lambda warm starts
+};
+```
+
+### Models
+
+```typescript
+import mongoose, { Schema, Document } from "mongoose";
+
+interface IUser extends Document {
+  email: string;
+  name: string;
+}
+
+const userSchema = new Schema<IUser>({
+  email: { type: String, required: true },
+  name: { type: String, required: true },
+}, { timestamps: true });
+
+export const User = mongoose.model<IUser>("User", userSchema);
+```
+
+### Mocking
+
+```typescript
+vi.mock("@jaypie/mongoose", async () => {
+  const { mockMongoose } = await import("@jaypie/testkit");
+  return mockMongoose(vi);
+});
+```
+
+## Migration Guides
+
+### Mongoose to DynamoDB
+
+1. Define DynamoDB item types (see `skill("dynamodb")`)
+2. Update data access patterns for single-table design
+3. Replace Mongoose queries with DynamoDB operations
+4. Update tests to mock DynamoDB instead of Mongoose
+
+### Core to Kit
+
+Direct replacement - same exports, new package name:
+
+```bash
+npm uninstall @jaypie/core
+npm install @jaypie/kit
+```
+
+Update imports throughout codebase.
+
+## When to Keep Legacy
+
+Keep legacy patterns when:
+- Existing production system is stable
+- Migration cost outweighs benefits
+- Team expertise is in legacy stack
+- Database has significant existing data
+
+Migrate when:
+- Starting new features
+- Performance issues arise
+- Scaling requirements change
+- Simplifying architecture
+

package/skills/logs.md

@@ -0,0 +1,160 @@
+---
+description: Logging patterns and conventions
+related: debugging, datadog, variables
+---
+
+# Logging Patterns
+
+Jaypie provides structured logging for observability.
+
+## Basic Usage
+
+```typescript
+import { log } from "jaypie";
+
+log.trace("Detailed debug info");
+log.debug("Debug information");
+log.info("Informational message");
+log.warn("Warning message");
+log.error("Error message");
+log.fatal("Fatal error");
+```
+
+## Structured Logging
+
+Always include context as the second argument:
+
+```typescript
+log.info("User logged in", {
+  userId: user.id,
+  email: user.email,
+  method: "oauth",
+});
+
+log.error("Payment failed", {
+  orderId: order.id,
+  amount: order.total,
+  error: error.message,
+});
+```
+
+## Log Levels
+
+| Level | Use For |
+|-------|---------|
+| trace | Very detailed debugging (loops, iterations) |
+| debug | Development debugging |
+| info | Normal operations, business events |
+| warn | Unexpected but handled situations |
+| error | Errors that need attention |
+| fatal | Application cannot continue |
+
+## Setting Log Level
+
+Via environment variable:
+
+```bash
+LOG_LEVEL=debug npm run dev
+LOG_LEVEL=trace npm test
+```
+
+In production, typically `info` or `warn`.
+
+## Request Context
+
+Include request identifiers for tracing:
+
+```typescript
+log.info("Processing request", {
+  requestId: req.id,
+  path: req.path,
+  userId: req.user?.id,
+});
+```
+
+## Error Logging
+
+Log errors with full context:
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  log.error("Operation failed", {
+    error: error.message,
+    stack: error.stack,
+    input: sanitizedInput,
+  });
+  throw error;
+}
+```
+
+## Sensitive Data
+
+Never log sensitive data:
+
+```typescript
+// BAD
+log.info("User auth", { password: user.password });
+
+// GOOD
+log.info("User auth", { userId: user.id, hasPassword: !!user.password });
+```
+
+## Searching Logs
+
+### Via MCP (Datadog)
+
+```
+# Search by requestId
+datadog_logs --query "@requestId:abc-123"
+
+# Search errors
+datadog_logs --query "status:error" --from "now-1h"
+
+# Search by user
+datadog_logs --query "@userId:user-456"
+```
+
+### Via MCP (CloudWatch)
+
+```
+aws_logs_filter_log_events \
+  --logGroupName "/aws/lambda/my-function" \
+  --filterPattern "ERROR"
+```
+
+## Log Format
+
+Jaypie logs are JSON-formatted for Datadog:
+
+```json
+{
+  "level": "info",
+  "message": "User logged in",
+  "timestamp": "2024-01-15T10:00:00.000Z",
+  "userId": "user-123",
+  "method": "oauth",
+  "dd": {
+    "trace_id": "abc123",
+    "span_id": "def456"
+  }
+}
+```
+
+## Lambda Logging
+
+Lambda handlers automatically add context:
+
+```typescript
+import { lambdaHandler } from "@jaypie/lambda";
+
+export const handler = lambdaHandler(async (event) => {
+  // Logs automatically include:
+  // - requestId
+  // - functionName
+  // - cold_start indicator
+  log.info("Processing", { customField: "value" });
+});
+```
+

package/skills/mocks.md

@@ -0,0 +1,174 @@
+---
+description: Mock patterns via @jaypie/testkit
+related: tests, errors
+---
+
+# Testing Mocks
+
+`@jaypie/testkit` provides mocks for Jaypie packages in tests.
+
+## Installation
+
+```bash
+npm install -D @jaypie/testkit
+```
+
+## Setup
+
+In your test setup file:
+
+```typescript
+// vitest.setup.ts
+import { vi } from "vitest";
+
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+```
+
+Configure in vitest.config.ts:
+
+```typescript
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+## Available Mocks
+
+### Main Package (jaypie)
+
+```typescript
+vi.mock("jaypie", async () => {
+  const { mockJaypie } = await import("@jaypie/testkit");
+  return mockJaypie(vi);
+});
+
+// Mocked: log, getSecret, sendMessage, etc.
+```
+
+### Logger
+
+```typescript
+vi.mock("@jaypie/logger", async () => {
+  const { mockLogger } = await import("@jaypie/testkit");
+  return mockLogger(vi);
+});
+```
+
+### AWS
+
+```typescript
+vi.mock("@jaypie/aws", async () => {
+  const { mockAws } = await import("@jaypie/testkit");
+  return mockAws(vi);
+});
+```
+
+### Legacy Mocks
+
+For legacy packages, see `skill("legacy")`.
+
+## Using Mocks in Tests
+
+### Verify Logging
+
+```typescript
+import { log } from "jaypie";
+
+it("logs the operation", async () => {
+  await myFunction();
+
+  expect(log.info).toHaveBeenCalledWith(
+    "Operation completed",
+    expect.objectContaining({ userId: "123" })
+  );
+});
+```
+
+### Mock Secret Values
+
+```typescript
+import { getSecret } from "jaypie";
+
+beforeEach(() => {
+  vi.mocked(getSecret).mockResolvedValue("mock-api-key");
+});
+
+it("uses the API key", async () => {
+  const result = await myFunction();
+
+  expect(getSecret).toHaveBeenCalledWith("api-key-name");
+  expect(result.authenticated).toBe(true);
+});
+```
+
+### Mock Errors
+
+```typescript
+import { getSecret } from "jaypie";
+import { ConfigurationError } from "jaypie";
+
+it("handles missing secrets", async () => {
+  vi.mocked(getSecret).mockRejectedValue(
+    new ConfigurationError("Secret not found")
+  );
+
+  await expect(myFunction()).rejects.toThrow(ConfigurationError);
+});
+```
+
+## Mock Matchers
+
+### toBeJaypieError
+
+```typescript
+import { matchers } from "@jaypie/testkit";
+
+expect.extend(matchers);
+
+it("throws a Jaypie error", async () => {
+  await expect(myFunction()).rejects.toBeJaypieError();
+});
+```
+
+### toBeValidSchema
+
+```typescript
+it("returns valid schema", () => {
+  const result = buildSchema();
+  expect(result).toBeValidSchema();
+});
+```
+
+## Per-Test Mock Reset
+
+```typescript
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  vi.resetAllMocks();
+});
+```
+
+## Export Verification
+
+When adding exports to packages, update testkit:
+
+```typescript
+// packages/testkit/src/mocks/mockJaypie.ts
+export function mockJaypie(vi) {
+  return {
+    log: mockLog(vi),
+    getSecret: vi.fn().mockResolvedValue("mock"),
+    // Add new exports here
+    newFunction: vi.fn(),
+  };
+}
+```
+

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
+```