class-ai-agent 1.2.0

package/.claude/references/security-checklist.md

@@ -0,0 +1,94 @@
+# Security Checklist
+
+> Quick reference for security review. See `.claude/rules/security.md` for full rules.
+
+## Pre-Commit Checks
+
+- [ ] No secrets in code (API keys, passwords, tokens)
+- [ ] `.gitignore` excludes sensitive files (`.env`, credentials)
+- [ ] `.env.example` contains only placeholder values
+- [ ] No hardcoded URLs with credentials
+
+## Authentication
+
+- [ ] Passwords hashed with bcrypt (rounds >= 12) or argon2
+- [ ] Session cookies: `httpOnly`, `secure`, `sameSite: 'lax'`
+- [ ] JWT tokens have reasonable expiry (15min access, 7d refresh)
+- [ ] Rate limiting on auth endpoints (max 10 attempts/15min)
+- [ ] Logout invalidates session/token
+
+## Authorization
+
+- [ ] Every endpoint checks authentication
+- [ ] Resource ownership verified (no IDOR)
+- [ ] API keys are scoped appropriately
+- [ ] JWT signature, expiration, and issuer validated
+- [ ] Admin functions protected
+
+## Input Validation
+
+- [ ] All user input validated at system boundary
+- [ ] Allowlist validation preferred over blocklist
+- [ ] String lengths constrained
+- [ ] Numeric ranges validated
+- [ ] File uploads restricted by type and size
+- [ ] SQL queries parameterized (never string concat)
+
+## Security Headers
+
+```javascript
+// Required headers
+Content-Security-Policy: default-src 'self'
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Permissions-Policy: geolocation=(), camera=()
+```
+
+## CORS
+
+- [ ] Restrictive origin allowlist (no `*` in production)
+- [ ] Credentials mode appropriate
+- [ ] Methods and headers restricted
+
+## Data Protection
+
+- [ ] Sensitive fields excluded from API responses
+- [ ] No secrets in logs
+- [ ] PII encrypted when required
+- [ ] HTTPS enforced
+- [ ] Database backups encrypted
+
+## Dependencies
+
+```bash
+# Run regularly
+npm audit
+npm audit fix
+```
+
+- [ ] No critical vulnerabilities
+- [ ] Dependencies up to date
+- [ ] Lock file committed
+
+## Error Handling
+
+- [ ] Generic error messages in production
+- [ ] No stack traces exposed
+- [ ] No database details in errors
+- [ ] No internal paths revealed
+
+## OWASP Top 10 Quick Check
+
+| # | Vulnerability | Check |
+|---|--------------|-------|
+| 1 | Broken Access Control | Auth on all endpoints? |
+| 2 | Cryptographic Failures | Secrets encrypted? HTTPS? |
+| 3 | Injection | Inputs sanitized? Queries parameterized? |
+| 4 | Insecure Design | Threat modeling done? |
+| 5 | Security Misconfiguration | Headers set? Defaults changed? |
+| 6 | Vulnerable Components | `npm audit` clean? |
+| 7 | Auth Failures | Rate limiting? Strong passwords? |
+| 8 | Data Integrity | Signatures verified? |
+| 9 | Logging Failures | Security events logged? |
+| 10 | SSRF | External URLs validated? |

package/.claude/references/testing-patterns.md

@@ -0,0 +1,183 @@
+# Testing Patterns Reference
+
+> Quick reference for test patterns. See `.claude/rules/testing.md` for full rules.
+
+## Test Pyramid
+
+```
+         ┌─────────┐
+         │   E2E   │  5%   Critical user flows
+         ├─────────┤
+         │  Integ  │  15%  API + DB interactions
+         ├─────────┤
+         │  Unit   │  80%  Pure logic, fast
+         └─────────┘
+```
+
+## Test Structure (AAA)
+
+```javascript
+it('should [expected behavior] when [condition]', () => {
+  // Arrange — Setup
+  const user = createTestUser({ role: 'admin' });
+  
+  // Act — Execute
+  const result = checkPermission(user, 'delete');
+  
+  // Assert — Verify
+  expect(result).toBe(true);
+});
+```
+
+## Unit Test Example
+
+```javascript
+describe('calculateDiscount', () => {
+  it('should return 10% for orders over $100', () => {
+    expect(calculateDiscount(150)).toBe(15);
+  });
+
+  it('should return 0 for orders under $100', () => {
+    expect(calculateDiscount(50)).toBe(0);
+  });
+
+  it('should handle edge case at exactly $100', () => {
+    expect(calculateDiscount(100)).toBe(0);
+  });
+});
+```
+
+## Integration Test Example
+
+```javascript
+describe('POST /api/users', () => {
+  it('should create user and return 201', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@example.com', name: 'Test' })
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(response.status).toBe(201);
+    expect(response.body.data.email).toBe('test@example.com');
+    
+    // Verify in database
+    const user = await db.user.findUnique({ 
+      where: { email: 'test@example.com' } 
+    });
+    expect(user).toBeDefined();
+  });
+});
+```
+
+## E2E Test Example (Playwright)
+
+```javascript
+test('user can complete checkout flow', async ({ page }) => {
+  // Login
+  await page.goto('/login');
+  await page.fill('[name="email"]', 'user@example.com');
+  await page.fill('[name="password"]', 'password');
+  await page.click('button[type="submit"]');
+
+  // Add to cart
+  await page.goto('/products/1');
+  await page.click('button:has-text("Add to Cart")');
+
+  // Checkout
+  await page.goto('/checkout');
+  await page.fill('[name="card"]', '4242424242424242');
+  await page.click('button:has-text("Pay")');
+
+  // Verify
+  await expect(page.locator('.success-message')).toBeVisible();
+});
+```
+
+## React Component Test
+
+```javascript
+import { render, screen, fireEvent } from '@testing-library/react';
+
+describe('Counter', () => {
+  it('should increment count when button clicked', () => {
+    render(<Counter initialCount={0} />);
+    
+    const button = screen.getByRole('button', { name: /increment/i });
+    fireEvent.click(button);
+    
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+});
+```
+
+## Test Doubles
+
+```javascript
+// 1. Real (preferred)
+const db = createTestDatabase();
+
+// 2. Fake (in-memory)
+const fakeUserRepo = {
+  users: [],
+  create(user) { this.users.push(user); return user; },
+  findById(id) { return this.users.find(u => u.id === id); }
+};
+
+// 3. Stub (canned response)
+const stubbedApi = {
+  getUser: () => Promise.resolve({ id: '1', name: 'Test' })
+};
+
+// 4. Mock (verify interactions — use sparingly)
+const mockLogger = vi.fn();
+```
+
+## Naming Convention
+
+```javascript
+// Pattern: should [expected] when [condition]
+
+// ✅ Good
+'should return null when user not found'
+'should throw ValidationError when email invalid'
+'should emit event when order placed'
+
+// ❌ Bad
+'works'
+'test user'
+'error handling'
+```
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Testing internals | Breaks on refactor | Test behavior |
+| Shared state | Tests affect each other | Reset in beforeEach |
+| Flaky tests | Random failures | Deterministic data |
+| Over-mocking | False confidence | Real implementations |
+| No assertions | Test always passes | Assert outcomes |
+| Magic numbers | Hard to understand | Named constants |
+
+## Coverage Thresholds
+
+```javascript
+// vitest.config.js
+coverage: {
+  thresholds: {
+    lines: 80,
+    branches: 80,
+    functions: 80,
+    statements: 80
+  }
+}
+```
+
+## Commands
+
+```bash
+npm test                  # Run all tests
+npm test -- --watch       # Watch mode
+npm test -- --coverage    # Coverage report
+npm run test:e2e          # E2E tests
+```

package/.claude/rules/api-conventions.md

@@ -0,0 +1,79 @@
+# API Conventions
+
+## REST API Design Standards
+
+### URL Structure
+- Use **kebab-case** for URL paths: `/api/user-profiles`
+- Use **plural nouns** for resource collections: `/api/users`, `/api/products`
+- Nest related resources: `/api/users/:id/orders`
+- API version prefix: `/api/v1/...`
+
+### HTTP Methods
+| Method | Usage |
+|--------|-------|
+| GET | Read resources (idempotent) |
+| POST | Create new resource |
+| PUT | Replace entire resource |
+| PATCH | Partial update |
+| DELETE | Remove resource |
+
+### HTTP Status Codes
+| Code | Meaning |
+|------|---------|
+| 200 | OK — Successful GET/PUT/PATCH |
+| 201 | Created — Successful POST |
+| 204 | No Content — Successful DELETE |
+| 400 | Bad Request — Invalid input |
+| 401 | Unauthorized — Not authenticated |
+| 403 | Forbidden — No permission |
+| 404 | Not Found |
+| 409 | Conflict |
+| 422 | Unprocessable Entity — Validation failed |
+| 500 | Internal Server Error |
+
+### Request/Response Format
+```json
+// Success response
+{
+  "success": true,
+  "data": { ... },
+  "message": "Optional message"
+}
+
+// Error response
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human readable message",
+    "details": [ ... ]
+  }
+}
+
+// Paginated list response
+{
+  "success": true,
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+### Naming Conventions
+- Request/response body fields: **camelCase**
+- Query parameters: **camelCase**
+- Always return consistent field names
+
+### Filtering & Pagination
+```
+GET /api/users?page=1&limit=20&sortBy=createdAt&order=desc
+GET /api/products?category=electronics&minPrice=100
+```
+
+### Documentation
+- Every endpoint MUST have JSDoc/Swagger annotations
+- Include request body schema, response schema, and error codes

package/.claude/rules/clean-code.md

@@ -0,0 +1,205 @@
+# Clean Code — JavaScript Rules
+> Source: [clean-code-javascript](https://github.com/ryanmcdermott/clean-code-javascript) by Ryan McDermott
+
+## 📦 Variables
+
+### ✅ Use meaningful, pronounceable names
+```js
+// ❌ Bad
+const yyyymmdstr = moment().format('YYYY/MM/DD');
+
+// ✅ Good
+const currentDate = moment().format('YYYY/MM/DD');
+```
+
+### ✅ Same vocabulary for same type
+```js
+// ❌ getUserInfo(), getClientData(), getCustomerRecord()
+// ✅ getUser()
+```
+
+### ✅ Use searchable names (no magic numbers)
+```js
+// ❌ setTimeout(blastOff, 86400000);
+const MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000;
+setTimeout(blastOff, MILLISECONDS_PER_DAY); // ✅
+```
+
+### ✅ Use explanatory variables
+```js
+// ❌ Bad
+saveCityZipCode(address.match(regex)[1], address.match(regex)[2]);
+
+// ✅ Good
+const [_, city, zipCode] = address.match(cityZipCodeRegex) || [];
+saveCityZipCode(city, zipCode);
+```
+
+### ✅ Avoid mental mapping — be explicit
+```js
+// ❌ locations.forEach(l => { dispatch(l); });
+// ✅ locations.forEach(location => { dispatch(location); });
+```
+
+### ✅ Don't add redundant context
+```js
+// ❌ const Car = { carMake, carModel, carColor }
+// ✅ const Car = { make, model, color }
+```
+
+### ✅ Use default parameters
+```js
+// ❌ const name = name || 'Default';
+// ✅ function create(name = 'Default') {}
+```
+
+---
+
+## 🔧 Functions
+
+### ✅ 2 arguments or fewer — use object destructuring for more
+```js
+// ❌ function createMenu(title, body, buttonText, cancellable) {}
+// ✅ function createMenu({ title, body, buttonText, cancellable }) {}
+```
+
+### ✅ Functions should do ONE thing
+```js
+// ❌ emailClients() — fetches DB + checks active + sends email
+// ✅ emailActiveClients() calls isActiveClient() separately
+```
+
+### ✅ Function names should say what they do
+```js
+// ❌ addToDate(date, 1)     → unclear what is added
+// ✅ addMonthToDate(1, date) → crystal clear
+```
+
+### ✅ One level of abstraction per function
+```js
+// ❌ parseBetterJSAlternative() — tokenizes + parses + AST walks in one function
+// ✅ parseBetterJSAlternative() → calls tokenize() → calls parse()
+```
+
+### ✅ Remove duplicate code — extract shared logic
+### ✅ No flag parameters — split into separate functions
+```js
+// ❌ function createFile(name, isTemp) { if (isTemp) ... }
+// ✅ function createFile(name) {}
+//    function createTempFile(name) {}
+```
+
+### ✅ Avoid Side Effects
+- Don't mutate global state
+- Don't mutate function arguments (use copies)
+```js
+// ✅ Return new array instead of mutating
+function addItemToCart(cart, item) {
+  return [...cart, { item, date: Date.now() }];
+}
+```
+
+### ✅ Favor functional programming
+```js
+// ❌ for loop with mutations
+// ✅ filter(), map(), reduce()
+const totalOutput = programmerOutput
+  .filter(p => p.linesOfCode > 0)
+  .reduce((acc, p) => acc + p.linesOfCode, 0);
+```
+
+### ✅ Encapsulate conditionals
+```js
+// ❌ if (fsm.state === 'fetching' && isEmpty(listNode)) {}
+// ✅ if (shouldShowSpinner(fsmInstance, listNodeInstance)) {}
+```
+
+### ✅ Avoid negative conditionals
+```js
+// ❌ if (!isNotDOMNodePresent(node)) {}
+// ✅ if (isDOMNodePresent(node)) {}
+```
+
+### ✅ Remove dead code immediately
+
+---
+
+## 🏛️ Classes
+
+### ✅ Prefer ES6 classes
+### ✅ Use method chaining (builder pattern)
+```js
+class QueryBuilder {
+  select(fields) { this.fields = fields; return this; }
+  from(table) { this.table = table; return this; }
+  build() { return `SELECT ${this.fields} FROM ${this.table}`; }
+}
+new QueryBuilder().select('*').from('users').build();
+```
+
+### ✅ Prefer composition over inheritance
+> "Favor has-a over is-a"
+
+---
+
+## 🧱 SOLID Principles
+
+| Principle | Rule |
+|-----------|------|
+| **S** — Single Responsibility | One class = one job. Never combine unrelated concerns |
+| **O** — Open/Closed | Open for extension, closed for modification |
+| **L** — Liskov Substitution | Subclasses must be substitutable for their base class |
+| **I** — Interface Segregation | Clients shouldn't depend on interfaces they don't use |
+| **D** — Dependency Inversion | Depend on abstractions, not concretions |
+
+```js
+// ✅ D — Dependency Inversion
+class InventoryService {
+  constructor(inventoryRequester) { // inject the dependency
+    this.inventoryRequester = inventoryRequester;
+  }
+  requestItems(customer) {
+    return this.inventoryRequester.requestItem(customer.purchaseHistory);
+  }
+}
+```
+
+---
+
+## ⚡ Concurrency
+
+### ✅ Use Promises over callbacks
+### ✅ Use async/await over Promises
+```js
+// ✅ Clearest form
+async function getCleanCodeArticle() {
+  try {
+    const response = await request.get(cleanCodeUrl);
+    await fs.writeFile('article.html', response);
+  } catch (err) {
+    console.error(err);
+  }
+}
+```
+
+---
+
+## 🗒️ Comments
+
+### ✅ Only comment business logic complexity
+### ❌ Never leave commented-out code
+### ❌ No journal comments (use git log instead)
+### ❌ No positional markers (`/////`)
+```js
+// ✅ Good comment — explains WHY
+// We retry 3x because OAuth2 tokens can have clock skew
+const MAX_RETRIES = 3;
+```
+
+---
+
+## 📐 Formatting
+
+- Use consistent capitalization (camelCase for vars/fns, PascalCase for classes, UPPER_SNAKE for constants)
+- Keep callers and callees close in the file
+- Related code should appear together

package/.claude/rules/code-style.md

@@ -0,0 +1,86 @@
+# Code Style Guide
+
+## General Principles
+- **Clarity over cleverness** — Write code that is easy to read and understand
+- **Consistency** — Follow existing patterns in the codebase
+- **DRY** — Don't Repeat Yourself, but don't over-abstract
+
+## JavaScript / TypeScript
+
+### Formatting
+- Indentation: **2 spaces** (no tabs)
+- Max line length: **100 characters**
+- Use **single quotes** for strings
+- Always use **semicolons**
+- Trailing commas in multi-line structures
+
+### Naming
+```js
+// Variables and functions: camelCase
+const userProfile = {};
+function getUserById(id) {}
+
+// Classes and interfaces: PascalCase
+class UserService {}
+interface UserRepository {}
+
+// Constants: UPPER_SNAKE_CASE
+const MAX_RETRY_COUNT = 3;
+const API_BASE_URL = 'https://api.example.com';
+
+// Files: kebab-case
+// user-service.js, auth-middleware.js
+```
+
+### Functions
+```js
+// ✅ Good — Arrow functions for simple operations
+const double = (x) => x * 2;
+
+// ✅ Good — Named functions for complex logic
+function processUserData(user) {
+  // ...
+}
+
+// ❌ Avoid — Functions longer than 30 lines (extract helpers)
+```
+
+### Async/Await
+```js
+// ✅ Always use async/await over raw promises
+async function fetchUser(id) {
+  try {
+    const user = await userRepository.findById(id);
+    return user;
+  } catch (error) {
+    throw new AppError('User not found', 404);
+  }
+}
+
+// ❌ Avoid promise chains
+fetchUser(id).then(...).catch(...);
+```
+
+### Imports
+```js
+// Order: 1. Node built-ins, 2. External deps, 3. Internal modules
+import path from 'path';
+import express from 'express';
+import { UserService } from './user-service.js';
+```
+
+## Comments
+```js
+// ✅ Explain WHY, not WHAT
+// We retry 3 times because the external API has transient failures
+const MAX_RETRIES = 3;
+
+// ❌ Avoid obvious comments
+// Set x to 5
+const x = 5;
+```
+
+## File Organization
+- One class/service per file
+- Group related files in feature folders
+- Index files for clean imports

package/.claude/rules/database.md

@@ -0,0 +1,60 @@
+doc# Database Rules
+
+## General Rules
+- **Never** write raw SQL strings directly in business logic
+- Always use an ORM (Prisma/Sequelize/TypeORM) or query builder
+- All database calls must be inside try/catch blocks
+- Use **transactions** for multi-step operations
+
+## Connection Management
+```js
+// ✅ Use connection pooling
+const pool = new Pool({ max: 10, idleTimeoutMillis: 30000 });
+
+// ❌ Never create a new connection per request
+```
+
+## Query Best Practices
+```js
+// ✅ Select only needed fields
+const user = await db.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true }
+});
+
+// ❌ Avoid SELECT *
+const user = await db.user.findUnique({ where: { id } });
+
+// ✅ Use pagination for lists
+const users = await db.user.findMany({
+  take: limit,
+  skip: (page - 1) * limit,
+  orderBy: { createdAt: 'desc' }
+});
+```
+
+## Transactions
+```js
+// ✅ Use transactions for atomic operations
+await db.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.update({ where: { id: productId }, data: { stock: { decrement: 1 } } });
+  return order;
+});
+```
+
+## Migrations
+- Always use migration files, never modify the database schema directly
+- Migration files are version-controlled and immutable
+- Run migrations in CI/CD before deploying
+
+## Naming Conventions
+- Tables: **snake_case** plural (`user_profiles`, `order_items`)
+- Columns: **snake_case** (`created_at`, `user_id`)
+- Indexes: `idx_[table]_[column]`
+- Foreign keys: `fk_[table]_[referenced_table]`
+
+## Security
+- Never log query results containing sensitive data (passwords, tokens)
+- Use parameterized queries — never string concatenation
+- Apply row-level security where applicable