class-ai-agent 1.2.3 → 1.3.0

package/.kiro/references/accessibility-checklist.md

@@ -0,0 +1,174 @@
+# Accessibility Checklist (WCAG 2.1 AA)
+
+> Ensure your application is usable by everyone.
+
+## Keyboard Navigation
+
+- [ ] All interactive elements focusable with Tab
+- [ ] Focus order is logical (follows visual order)
+- [ ] Focus indicator visible (never `outline: none`)
+- [ ] Skip link to main content
+- [ ] No keyboard traps
+- [ ] Custom components work with Enter/Space
+
+```jsx
+// ✅ Good: Custom button with keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') handleClick();
+  }}
+>
+  Click me
+</div>
+
+// ✅ Better: Use native button
+<button onClick={handleClick}>Click me</button>
+```
+
+## Screen Readers
+
+### Semantic HTML
+- [ ] Use semantic elements (`<nav>`, `<main>`, `<article>`, etc.)
+- [ ] Headings in logical order (h1 → h2 → h3)
+- [ ] Lists use `<ul>`, `<ol>`, `<dl>`
+- [ ] Tables have `<th>` with scope
+
+### ARIA
+- [ ] Images have alt text (empty `alt=""` for decorative)
+- [ ] Form inputs have labels
+- [ ] Buttons have accessible names
+- [ ] Dynamic content announced (aria-live)
+- [ ] Modals trap focus and have aria-modal
+
+```jsx
+// ✅ Good: Accessible form
+<label htmlFor="email">Email</label>
+<input id="email" type="email" aria-describedby="email-hint" />
+<span id="email-hint">We'll never share your email</span>
+
+// ✅ Good: Accessible icon button
+<button aria-label="Close menu">
+  <CloseIcon aria-hidden="true" />
+</button>
+
+// ✅ Good: Live region for updates
+<div aria-live="polite" aria-atomic="true">
+  {notification}
+</div>
+```
+
+## Visual Design
+
+### Color
+- [ ] Color contrast ratio ≥ 4.5:1 (text)
+- [ ] Color contrast ratio ≥ 3:1 (large text, UI components)
+- [ ] Information not conveyed by color alone
+- [ ] Links distinguishable from text (underline or contrast)
+
+### Text
+- [ ] Text resizable to 200% without loss
+- [ ] Line height ≥ 1.5
+- [ ] No text in images (except logos)
+
+### Motion
+- [ ] Respect `prefers-reduced-motion`
+- [ ] No flashing content (> 3 flashes/second)
+- [ ] Animations can be paused
+
+```css
+/* Respect motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Forms
+
+- [ ] All inputs have visible labels
+- [ ] Required fields marked
+- [ ] Error messages associated with inputs
+- [ ] Autocomplete attributes used
+- [ ] Form validation accessible
+
+```jsx
+// ✅ Accessible error message
+<input
+  id="email"
+  aria-invalid={hasError}
+  aria-describedby={hasError ? 'email-error' : undefined}
+/>
+{hasError && (
+  <span id="email-error" role="alert">
+    Please enter a valid email address
+  </span>
+)}
+```
+
+## Interactive Components
+
+### Buttons & Links
+- [ ] Buttons for actions, links for navigation
+- [ ] Link text is descriptive (not "click here")
+- [ ] Disabled state communicated
+
+### Modals/Dialogs
+- [ ] Focus trapped inside modal
+- [ ] Close with Escape key
+- [ ] Focus returns on close
+- [ ] `role="dialog"` and `aria-modal="true"`
+
+### Menus & Dropdowns
+- [ ] Arrow key navigation
+- [ ] `role="menu"` and `role="menuitem"`
+- [ ] Current item indicated
+
+## Testing Tools
+
+```bash
+# Automated testing
+npx axe-cli https://example.com
+npx pa11y https://example.com
+
+# Browser extensions
+- axe DevTools (Chrome)
+- WAVE (Chrome/Firefox)
+- Accessibility Insights (Chrome)
+```
+
+### Manual Testing
+- [ ] Navigate with keyboard only
+- [ ] Test with screen reader (VoiceOver/NVDA)
+- [ ] Zoom to 200%
+- [ ] Use high contrast mode
+- [ ] Test with reduced motion
+
+## ARIA Roles Quick Reference
+
+| Role | Use For |
+|------|---------|
+| `button` | Clickable elements (prefer `<button>`) |
+| `link` | Navigation (prefer `<a>`) |
+| `dialog` | Modal windows |
+| `alert` | Important messages |
+| `status` | Status updates |
+| `navigation` | Nav sections (prefer `<nav>`) |
+| `main` | Main content (prefer `<main>`) |
+| `region` | Distinct sections with label |
+| `tablist`, `tab`, `tabpanel` | Tab interfaces |
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Missing alt text | Add descriptive alt or `alt=""` |
+| Low contrast | Increase color contrast |
+| Missing form labels | Add `<label>` elements |
+| Focus not visible | Don't remove outline, style it |
+| Mouse-only interactions | Add keyboard handlers |
+| Auto-playing media | Add controls, respect preferences |

package/.kiro/references/agent-continuity.md

@@ -0,0 +1,42 @@
+# Agent continuity — quick reference
+
+## Files
+
+| Path | Role |
+|------|------|
+| `.agent/SESSION.md` | Live handoff (commit to git) |
+| `.agent/SESSION.template.md` | Schema reference |
+| `.agent/README.md` | Human overview |
+| `tasks/todo.md` | Task checklist (workflow) |
+| `SPEC.md` | Feature spec (workflow) |
+
+## Commands
+
+| Command | When |
+|---------|------|
+| **`/resume`** | Start of session — read SESSION, summarize, continue |
+| **`/handoff`** | End of session — write SESSION, sync tasks |
+
+## Read order (resume)
+
+1. `.agent/SESSION.md`
+2. `tasks/todo.md`
+3. Linked spec from SESSION Pointers
+
+## Install
+
+```bash
+npx class-ai-agent
+```
+
+Creates `.agent/` and seeds `SESSION.md` from template.
+
+## Rules
+
+- **Cursor:** `.cursor/rules/agent-continuity.mdc` (`alwaysApply`)
+- **Claude:** `.claude/rules/agent-continuity.md`
+- **Kiro:** `.kiro/steering/agent-continuity.md` (`inclusion: always`)
+
+## Skill
+
+`.cursor/skills/agent-continuity/SKILL.md` — full handoff/resume checklists.

package/.kiro/references/codegraph.md

@@ -0,0 +1,86 @@
+# CodeGraph reference
+
+[CodeGraph](https://github.com/colbymchenry/codegraph) is a local, tree-sitter–parsed knowledge graph exposed to agents via MCP. **class-ai-agent** installs Cursor and Kiro MCP wiring plus usage rules, and runs `codegraph init -i` after scaffolding.
+
+## Kiro (included with class-ai-agent)
+
+| Item | Path |
+|------|------|
+| MCP config | `.kiro/settings/mcp.json` |
+| Usage rules | `.kiro/steering/codegraph.md` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Restart Kiro after install so MCP connects.
+2. Confirm **CodeGraph** appears under MCP in Kiro (IDE or CLI).
+3. Use `codegraph_*` tools for structural questions; grep/read for literal text.
+
+**Manual index:** `npx @colbymchenry/codegraph init -i`
+
+**Skip auto-index on install:** `CODEGRAPH_SKIP_INIT=1 npx class-ai-agent`
+
+## Kiro (included with class-ai-agent)
+
+| Item | Path |
+|------|------|
+| MCP config | `.kiro/settings/mcp.json` |
+| Usage rules | `.kiro/steering/codegraph.md` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Restart Kiro after install so MCP connects.
+2. Confirm **CodeGraph** under MCP in Kiro IDE or CLI settings.
+3. Use `codegraph_*` tools for structural questions.
+
+See `.kiro/references/codegraph.md` for full notes.
+
+## Claude Code
+
+Project scaffolding does **not** add Claude MCP config. Install CodeGraph globally:
+
+```bash
+npx @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+## Cursor
+
+Cursor users get `.cursor/mcp.json` and `.cursor/rules/codegraph.mdc` from the same package. See `.cursor/references/codegraph.md`.
+
+## Requirements
+
+- **Node 20+** recommended for CodeGraph (class-ai-agent CLI itself supports Node 16.7+).
+- First index can take a minute on large repos; progress prints during `npx class-ai-agent` install.
+
+## Tool parameters
+
+| Tool | Pass | Not |
+|------|------|-----|
+| `codegraph_search` | `query`, optional `limit` | — |
+| `codegraph_context` | **`task`** (natural-language area), optional **`maxNodes`** | `query`, `limit` |
+
+Example — wrong (search-style args on context):
+
+```json
+{ "query": "auth flow", "limit": 15 }
+```
+
+→ `Error: task must be a non-empty string`
+
+Example — correct:
+
+```json
+{ "task": "how authentication flow works", "maxNodes": 15 }
+```
+
+**Session handoff** (`/resume`, `.agent/SESSION.md`) is not a CodeGraph call — read those files with the editor Read tool.
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `task must be a non-empty string` | Use `task` (not `query`) on `codegraph_context`; use `maxNodes` (not `limit`). For `/resume`, read `.agent/SESSION.md` instead. |
+| MCP “not initialized” | Run `npx @colbymchenry/codegraph init -i` in project root |
+| MCP not connecting | Reload Cursor; verify `.cursor/mcp.json`; test `npx @colbymchenry/codegraph serve --mcp` |
+| Stale symbols after edit | Wait ~2s for watcher sync, or check staleness banner in tool output |
+| Init failed during install | Run `npx @colbymchenry/codegraph init -i` manually |
+
+Upstream: [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)

package/.kiro/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/.kiro/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? |