class-ai-agent 1.4.0 → 1.5.0

package/.agents/references/performance-checklist.md

@@ -0,0 +1,150 @@
+# Performance Checklist
+
+> Quick reference for performance optimization.
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| **LCP** (Largest Contentful Paint) | < 2.5s | 2.5-4s | > 4s |
+| **INP** (Interaction to Next Paint) | < 200ms | 200-500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 |
+
+## Frontend Performance
+
+### Critical Render Path
+- [ ] Minimize critical CSS (inline above-fold styles)
+- [ ] Defer non-critical JavaScript
+- [ ] Preload critical resources
+- [ ] Optimize font loading (font-display: swap)
+
+### Images
+- [ ] Use modern formats (WebP, AVIF)
+- [ ] Implement lazy loading
+- [ ] Serve responsive sizes (srcset)
+- [ ] Use CDN for static assets
+- [ ] Set explicit width/height (prevent CLS)
+
+### JavaScript
+- [ ] Code splitting (dynamic imports)
+- [ ] Tree shaking enabled
+- [ ] Bundle size monitored (< 200KB initial)
+- [ ] No unused dependencies
+
+### React Specific
+- [ ] Memoize expensive computations (useMemo)
+- [ ] Prevent unnecessary re-renders (React.memo)
+- [ ] Virtualize long lists (react-window)
+- [ ] Use Suspense for code splitting
+
+```javascript
+// ✅ Good: Memoized component
+const ExpensiveList = React.memo(({ items }) => {
+  return items.map(item => <Item key={item.id} {...item} />);
+});
+
+// ✅ Good: Memoized computation
+const sortedItems = useMemo(
+  () => items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+```
+
+## Backend Performance
+
+### Database
+- [ ] Indexes on queried columns
+- [ ] No N+1 queries
+- [ ] Pagination implemented
+- [ ] Connection pooling configured
+- [ ] Query timeouts set
+
+```javascript
+// ❌ N+1 Problem
+const users = await db.user.findMany();
+for (const user of users) {
+  user.orders = await db.order.findMany({ where: { userId: user.id } });
+}
+
+// ✅ Fixed: Include relation
+const users = await db.user.findMany({
+  include: { orders: true }
+});
+```
+
+### Caching
+- [ ] Cache frequently accessed data
+- [ ] Appropriate TTLs set
+- [ ] Cache invalidation strategy
+- [ ] CDN for static content
+
+```javascript
+// Cache pattern
+async function getUser(id) {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+  
+  const user = await db.user.findUnique({ where: { id } });
+  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
+  return user;
+}
+```
+
+### API
+- [ ] Response compression (gzip/brotli)
+- [ ] Pagination for lists
+- [ ] Field selection (select only needed)
+- [ ] Async operations for slow tasks
+
+```javascript
+// ✅ Good: Paginated API
+GET /api/users?page=1&limit=20&fields=id,name,email
+```
+
+## Measurement Commands
+
+```bash
+# Lighthouse (Chrome)
+npx lighthouse https://example.com --output=json
+
+# Bundle analysis
+npx webpack-bundle-analyzer stats.json
+
+# Check bundle size
+npx bundlephobia <package-name>
+
+# Database query analysis
+EXPLAIN ANALYZE SELECT * FROM users WHERE email = '...';
+
+# Redis latency
+redis-cli --latency
+
+# API response time
+curl -o /dev/null -s -w '%{time_total}\n' https://api.example.com/users
+```
+
+## Performance Budget
+
+| Resource | Budget |
+|----------|--------|
+| Initial JS | < 200KB |
+| Initial CSS | < 50KB |
+| Total page weight | < 1MB |
+| Time to Interactive | < 3s |
+| API response (p95) | < 200ms |
+
+## Monitoring
+
+- [ ] Real User Monitoring (RUM) enabled
+- [ ] Synthetic monitoring configured
+- [ ] Alerting on degradation
+- [ ] Performance tracked in CI
+
+```javascript
+// Example: Track Core Web Vitals
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+onLCP(metric => sendToAnalytics('LCP', metric.value));
+onINP(metric => sendToAnalytics('INP', metric.value));
+onCLS(metric => sendToAnalytics('CLS', metric.value));
+```

package/.agents/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/.agents/references/supabase.md

@@ -0,0 +1,55 @@
+# Supabase reference
+
+[class-ai-agent](https://github.com/khoantd/class-ai-agent) bundles official [Supabase Agent Skills](https://github.com/supabase/agent-skills) and wires the **Supabase MCP** server for Cursor and Kiro.
+
+## Skills
+
+| Skill | Use when |
+|-------|----------|
+| `supabase` | Any Supabase product work: Database, Auth, Edge Functions, Realtime, Storage, CLI, MCP, migrations, RLS, `supabase-js`, `@supabase/ssr` |
+| `supabase-postgres-best-practices` | SQL, schema design, indexes, pooling, RLS performance, query review |
+
+Paths: `.cursor/skills/supabase/`, `.cursor/skills/supabase-postgres-best-practices/` (and `.claude/skills/`, `.kiro/skills/` after install).
+
+Invoke with **`@`** mention or let the agent load them when the task matches. See each skill’s `SKILL.md` for security checklists and workflow.
+
+**Maintainers:** refresh vendored copies with `npm run sync:supabase-skills` (pin in `scripts/supabase-skills.lock.json`).
+
+## MCP (Cursor & Kiro)
+
+| Tool | MCP config |
+|------|------------|
+| Cursor | `.cursor/mcp.json` → `mcpServers.supabase` |
+| Kiro | `.kiro/settings/mcp.json` → `mcpServers.supabase` |
+
+Server URL: `https://mcp.supabase.com/mcp?features=docs` (HTTP, OAuth 2.1).
+
+### After install
+
+1. **Reload** Cursor or **restart** Kiro so MCP servers connect.
+2. On first use, complete **OAuth** in the browser when prompted (Supabase account).
+3. Health check (expect `401` without a token — server is up):
+   ```bash
+   curl -so /dev/null -w "%{http_code}" "https://mcp.supabase.com/mcp"
+   ```
+
+Useful MCP tools include `search_docs`, `list_projects`, `list_tables`, `execute_sql`, `get_advisors`, `get_logs`, and migration helpers. Prefer `search_docs` over guessing API behavior.
+
+**Note:** Upstream skill text may refer to a project-root `.mcp.json`. In this scaffold, Supabase MCP lives only under `.cursor/mcp.json` and `.kiro/settings/mcp.json` — do not add a duplicate root `.mcp.json`.
+
+## Claude Code
+
+Skills install to `.claude/skills/`. Claude Code does not get MCP from this package by default. Options:
+
+- [Supabase MCP setup](https://supabase.com/docs/guides/getting-started/mcp)
+- [Supabase plugin for Claude Code](https://github.com/supabase/agent-skills)
+
+## Secrets
+
+Never commit service role keys, secret keys, or project tokens. Use environment variables per `.cursor/rules/security.mdc` (and `.claude/rules/security.md`, `.kiro/steering/security.md`).
+
+## Learn more
+
+- [Supabase AI skills docs](https://supabase.com/docs/guides/ai-tools/ai-skills)
+- [Upstream repository](https://github.com/supabase/agent-skills)
+- [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md) — license and pinned version

package/.agents/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/.agents/skills/agent-continuity/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: Agent Continuity
+description: Cross-tool session handoff and resume via .agent/SESSION.md
+---
+
+# Agent Continuity Skill
+
+## Purpose
+
+Keep **Cursor**, **Claude Code**, and **Kiro** aligned on the same in-flight work using committed **`.agent/SESSION.md`**.
+
+---
+
+## When to apply
+
+| Situation | Action |
+|-----------|--------|
+| New chat, same feature | **Resume** — read SESSION first |
+| End of session | **Handoff** — update SESSION |
+| Switch IDE/tool | **Handoff** then **Resume** in new tool |
+| Switch persona | Update Meta `persona`; handoff notes for next role |
+| Phase change (plan → build) | Update Meta `phase` |
+
+---
+
+## Handoff checklist
+
+- [ ] Meta: date, phase, tool, persona
+- [ ] Goal still accurate (one paragraph)
+- [ ] Done: bullets with paths/commits
+- [ ] In progress + blockers
+- [ ] Next: numbered for next agent
+- [ ] Decisions: non-obvious choices
+- [ ] Gotchas: failures, test commands, env
+- [ ] Pointers: spec, tasks, branch, key files
+- [ ] `tasks/todo.md` synced
+- [ ] No secrets or PII in SESSION
+
+---
+
+## Resume checklist
+
+- [ ] Read `.agent/SESSION.md`
+- [ ] Read `tasks/todo.md` if linked
+- [ ] Read SPEC if linked
+- [ ] `git status` vs SESSION expectations
+- [ ] Run sanity build/test if Gotchas say so
+- [ ] Post resumption summary to user
+- [ ] Execute first **Next** step via workflow command
+
+---
+
+## SESSION schema
+
+See **`.agent/SESSION.template.md`** for the canonical sections.
+
+---
+
+## Commands
+
+| Command | File |
+|---------|------|
+| `/handoff` | `.agents/workflows/handoff.md` (`.agents/`, `.agents/`) |
+| `/resume` | `.agents/workflows/resume.md` |
+
+---
+
+## Optional history
+
+Copy SESSION to `.agent/history/YYYY-MM-DD-slug.md` at milestones; commit for audit trail.