diff --git a/.claude/SETUP.md b/.claude/SETUP.md new file mode 100644 index 0000000..6c1c137 --- /dev/null +++ b/.claude/SETUP.md @@ -0,0 +1,299 @@ +# Claudia Setup Guide + +Complete setup guide for the Claudia development environment with Claude Code integration. + +## Prerequisites + +- Docker & Docker Compose +- Node.js 20+ +- Git +- GitHub CLI (`gh`) +- Python 3.11+ (for Serena) + +## Quick Start + +### 1. Clone and Install + +```bash +git clone +cd Claudia +cp .env.example .env +# Edit .env with your tokens +npm install +``` + +### 2. Start Services + +```bash +docker compose -f docker-compose.dev.yml up -d +``` + +This starts: +- **Ollama** (port 11434): Local LLM inference +- **SearXNG** (port 8080): Privacy-respecting search +- **SurrealDB** (port 8081): Multi-model database +- **Serena** (port 8384): Code analysis service + +### 3. Verify Services + +```bash +# Check all services are running +docker compose -f docker-compose.dev.yml ps + +# Test Ollama +curl http://localhost:11434/api/tags + +# Test SearXNG +curl http://localhost:8080 + +# Test SurrealDB +curl http://localhost:8081/health +``` + +## Environment Variables + +### Required + +**GITHUB_TOKEN** +- Required for: GitHub MCP, PR reviews, workflow automation +- Get from: https://github.com/settings/tokens +- Scopes needed: `repo`, `workflow`, `read:org` + +**ANTHROPIC_API_KEY** (for CI/CD only) +- Required for: GitHub Actions workflows with Claude Code +- Get from: https://console.anthropic.com/ +- Set as repository secret + +### Optional MCP Services + +**SERENA_API_KEY** +- Required for: Code review insights, pattern detection +- Get from: Your Serena instance or service provider +- Default host: http://localhost:8384 + +**CONTEXT7_API_KEY** +- Required for: Up-to-date framework/library documentation +- Get from: https://context7.io/ or Upstash +- Enables documentation lookups during reviews + +**PLAYWRIGHT_HEADLESS** +- Default: `true` +- Set to `false` for debugging browser automation +- Used by Playwright MCP server + +**PLAYWRIGHT_BROWSER** +- Default: `chromium` +- Options: `chromium`, `firefox`, `webkit` + +### Optional Monitoring + +**SENTRY_AUTH_TOKEN** & **SENTRY_ORG** +- For error tracking integration +- Get from: https://sentry.io/settings/account/api/auth-tokens/ + +**SLACK_BOT_TOKEN** & **SLACK_TEAM_ID** +- For workflow notifications +- Get from: https://api.slack.com/apps + +**CODECOV_TOKEN** +- For coverage reporting in CI +- Get from: https://codecov.io/ + +## MCP Servers + +Claudia uses 9 MCP servers for enhanced functionality: + +| Server | Purpose | Configuration | +|--------|---------|---------------| +| **github** | GitHub API access | GITHUB_TOKEN | +| **serena** | Code analysis & insights | SERENA_API_KEY, SERENA_HOST | +| **context7** | Documentation lookup | CONTEXT7_API_KEY | +| **playwright** | Browser automation | PLAYWRIGHT_HEADLESS, PLAYWRIGHT_BROWSER | +| **surrealdb** | Database queries | Auto-configured via Docker | +| **searxng** | Web search | Auto-configured via Docker | +| **ollama** | Local LLM | Auto-configured via Docker | +| **sentry** | Error tracking | SENTRY_AUTH_TOKEN, SENTRY_ORG | +| **slack** | Team notifications | SLACK_BOT_TOKEN, SLACK_TEAM_ID | + +## Custom Commands + +Available slash commands for Claude Code: + +- `/audit [directory]` - Comprehensive code quality audit +- `/test [files/flags]` - Run tests with optional arguments +- `/code-quality [directory]` - Code quality review +- `/docs-sync` - Check documentation sync +- `/pr-review [number]` - Review a pull request +- `/pr-summary` - Generate PR summary +- `/ticket [issue-number]` - Work on GitHub issue +- `/list-skills` - List available skills +- `/onboard` - Onboarding guide +- `/validate-config` - Validate configuration files + +## Hooks + +Claudia includes automated quality hooks: + +### Pre-Tool Hooks +- **Main branch protection**: Prevents editing on main branch + +### Post-Tool Hooks (after Edit/Write) +1. **Prettier formatting**: Auto-format JS/TS files +2. **Dependency installation**: Auto `npm install` when package.json changes +3. **Test runner**: Auto-run tests for changed test files +4. **Type checker**: TypeScript type checking (non-blocking) +5. **Duplicate detector**: Warns about potential code duplication + +### User Prompt Hooks +- **Skill evaluation**: Suggests relevant skills based on task + +## GitHub Actions Workflows + +### On Every PR +- **CI**: Lint, type-check, test, build +- **Claude Code Review**: Automated code review with Serena/Context7 +- **Semgrep**: Security scanning +- **CodeQL**: Semantic code analysis + +### Scheduled (Monthly) +- **Code Quality Review**: Random directory reviews with auto-fixes +- **Documentation Sync**: Ensure docs match code +- **Dependency Audit**: Security updates and dependency checks +- **Actions Usage Monitoring**: Track GitHub Actions usage + +### Scheduled (Weekly) +- **Auto-Improvement**: Autonomous codebase improvements + - Focus areas: docs, tests, performance, security, types, quality + - Uses Serena for insights, Context7 for best practices + - Creates PRs with improvements + +## Development Workflow + +### 1. Feature Development + +```bash +# Create feature branch +git checkout -b feature/my-feature + +# Develop (hooks auto-run on file changes) +# - Prettier formats on save +# - Tests run automatically +# - Type checking happens in background + +# Commit +git add . +git commit -m "feat: add new feature" + +# Push +git push -u origin feature/my-feature + +# Create PR +gh pr create +``` + +### 2. Code Review + +PRs automatically get Claude Code review with: +- TypeScript quality checks +- React patterns validation +- Security scanning +- Performance analysis +- Serena insights +- Context7 best practices + +### 3. Auto-Improvements + +Every Monday at 9 AM UTC: +- Claude analyzes recent changes +- Identifies improvement opportunities +- Makes fixes (docs, tests, performance, etc.) +- Creates PR with improvements + +## Troubleshooting + +### Hooks Failing + +If hooks fail with "command not found": +```bash +# Make hooks executable +chmod +x .claude/hooks/*.sh + +# Test hook manually +bash .claude/hooks/format-check.sh +``` + +### MCP Servers Not Working + +```bash +# Check Docker services +docker compose -f docker-compose.dev.yml ps + +# Restart services +docker compose -f docker-compose.dev.yml restart + +# Check logs +docker compose -f docker-compose.dev.yml logs ollama +``` + +### TypeScript Errors in Hooks + +Ensure `tsconfig.json` exists in project root: +```bash +npx tsc --init +``` + +### Playwright Installation + +If Playwright MCP fails: +```bash +# Install browsers +npx playwright install chromium + +# Or in DevContainer +npx playwright install-deps +``` + +## DevContainer + +For consistent development environment: + +```bash +# Open in VS Code +code . + +# Reopen in container +# Command Palette → "Reopen in Container" +``` + +Includes: +- Node.js 20 +- Docker-in-Docker +- Git & GitHub CLI +- Playwright with chromium +- All VS Code extensions +- Pre-configured settings + +## Best Practices + +### 1. Always Work on Feature Branches +Never commit directly to `main` - hooks will block you. + +### 2. Let Hooks Do Their Job +Don't bypass hooks unless absolutely necessary. They catch issues early. + +### 3. Use Custom Commands +Leverage `/audit`, `/test` for consistent quality checks. + +### 4. Review Auto-Improvement PRs +Weekly auto-improvements are autonomous but should be reviewed before merging. + +### 5. Keep Dependencies Updated +Monthly dependency audit workflow handles this automatically. + +## Support + +- Documentation: `CLAUDE.md` +- Commands: `/list-skills` +- Configuration: `.claude/settings.json` +- Hooks: `.claude/hooks/` +- Workflows: `.github/workflows/` diff --git a/.claude/commands/audit.md b/.claude/commands/audit.md new file mode 100644 index 0000000..1378f59 --- /dev/null +++ b/.claude/commands/audit.md @@ -0,0 +1,118 @@ +--- +description: Comprehensive code audit with quality checks, security scanning, and duplicate detection +allowed-tools: Read, Glob, Grep, Bash(npm:*), Bash(npx:*), Bash(git:*) +--- + +# Code Audit + +Perform a comprehensive audit of: ${ARGUMENTS:-the entire codebase} + +## Instructions + +### 1. **Identify Scope** + - Determine files to audit based on $ARGUMENTS + - Default to all `.ts`, `.tsx`, `.js`, `.jsx` files if no directory specified + - Exclude: `node_modules`, `dist`, `build`, `.next`, coverage reports + +### 2. **Automated Quality Checks** + +Run these checks in parallel: + +```bash +# Linting +npm run lint -- ${ARGUMENTS:-.} + +# Type checking +npx tsc --noEmit + +# Security scanning +npm audit --audit-level=moderate +npx better-npm-audit audit +``` + +### 3. **Duplicate Code Detection** + +Search for common duplication patterns: +- Similar function signatures +- Repeated GraphQL queries/mutations +- Duplicate React components +- Copy-pasted utility functions + +Use grep to find: +```bash +# Find duplicate exports +rg "^export (const|function|class)" --no-heading | sort | uniq -d + +# Find similar function names (potential duplicates) +rg "function \w+(Query|Mutation|Hook|Component)" -o --no-heading | sort | uniq -d +``` + +### 4. **Manual Code Review Checklist** + +For each file, verify: + +**TypeScript Quality**: +- [ ] No `any` types (use `unknown` instead) +- [ ] Proper type narrowing with type guards +- [ ] Interfaces preferred over types (except unions/intersections) +- [ ] No implicit any from missing types + +**Error Handling**: +- [ ] All async operations have error handlers +- [ ] User-facing errors show feedback +- [ ] Errors logged for debugging +- [ ] No silent failures + +**UI States** (React components): +- [ ] Loading state handled (only when no data) +- [ ] Error state with user feedback +- [ ] Empty state for lists/collections +- [ ] Success state clearly indicated + +**Mutations & Async Operations**: +- [ ] Buttons disabled during operations +- [ ] Loading indicators on buttons +- [ ] `onError` handler with user feedback +- [ ] Optimistic updates where appropriate + +**Security**: +- [ ] User input sanitized +- [ ] No SQL/NoSQL injection vectors +- [ ] No XSS vulnerabilities +- [ ] Sensitive data not logged +- [ ] API keys not hardcoded + +**Performance**: +- [ ] No unnecessary re-renders +- [ ] Proper memoization (useMemo, useCallback) +- [ ] Large lists virtualized +- [ ] Images optimized and lazy-loaded + +### 5. **Report Findings** + +Organize by severity: + +**🔴 Critical** (must fix immediately): +- Security vulnerabilities +- Runtime errors +- Data loss risks + +**🟡 Warning** (should fix soon): +- Type errors +- Missing error handling +- Duplicate code + +**🟢 Suggestion** (could improve): +- Code style inconsistencies +- Performance optimizations +- Missing tests + +### 6. **Create Action Items** + +For each finding: +1. File path with line number +2. Issue description +3. Recommended fix +4. Priority level + +Present as a markdown checklist that can be tracked. diff --git a/.claude/commands/test.md b/.claude/commands/test.md new file mode 100644 index 0000000..93d44e9 --- /dev/null +++ b/.claude/commands/test.md @@ -0,0 +1,83 @@ +--- +description: Run tests with optional filters and arguments +allowed-tools: Bash(npm:*), Bash(npx:*), Read, Glob +--- + +# Test Runner + +Run tests for: ${ARGUMENTS:-all files} + +## Instructions + +### 1. **Parse Arguments** + +Determine test mode from $ARGUMENTS: +- Specific file: `src/components/Button.test.tsx` +- Directory: `src/components/` +- Pattern: `Button` +- Watch mode: `--watch` +- Coverage: `--coverage` +- No arguments: Run all tests + +### 2. **Run Tests** + +Execute appropriate test command: + +```bash +# Specific file or directory +npm test -- ${ARGUMENTS} + +# With coverage +npm test -- --coverage ${ARGUMENTS} + +# Watch mode +npm test -- --watch ${ARGUMENTS} + +# All tests (no arguments) +npm test +``` + +### 3. **Additional Test Options** + +Support common Jest flags: +- `--watch` - Watch for changes +- `--coverage` - Generate coverage report +- `--updateSnapshot` or `-u` - Update snapshots +- `--verbose` - Detailed output +- `--bail` - Stop on first failure +- `--findRelatedTests ` - Test related to specific file +- `--onlyChanged` - Only test changed files (git) + +### 4. **Coverage Analysis** + +If `--coverage` flag is present: +- Show coverage summary +- Identify files below thresholds +- Highlight untested code paths + +### 5. **Failure Analysis** + +If tests fail: +- Show which tests failed +- Display error messages +- Suggest fixes for common issues: + - Missing mocks + - Async timing issues + - Snapshot mismatches + - Type errors in tests + +### 6. **Related Files** + +When testing a specific file, optionally check: +- Is there a corresponding test file? +- If not, offer to create one following TDD patterns +- Check if implementation file exists for test files + +## Examples + +```bash +/test src/components/Button.test.tsx +/test src/hooks/ --watch +/test --coverage +/test Button --updateSnapshot +``` diff --git a/.claude/hooks/duplicate-detector.sh b/.claude/hooks/duplicate-detector.sh new file mode 100755 index 0000000..2e9327a --- /dev/null +++ b/.claude/hooks/duplicate-detector.sh @@ -0,0 +1,67 @@ +#!/bin/bash +# Duplicate Code Detection Hook +# Runs after Edit/Write to detect potential code duplication + +set -euo pipefail + +# Only run for code files +if [[ ! "$CLAUDE_TOOL_INPUT_FILE_PATH" =~ \.(ts|tsx|js|jsx)$ ]]; then + exit 0 +fi + +# Skip if file doesn't exist +if [ ! -f "$CLAUDE_TOOL_INPUT_FILE_PATH" ]; then + exit 0 +fi + +file_path="$CLAUDE_TOOL_INPUT_FILE_PATH" +file_content=$(cat "$file_path") + +# Extract key patterns from the file +function extract_patterns() { + local file=$1 + + # Extract function/class/component names + rg "^export (const|function|class|interface|type) (\w+)" -o --no-filename "$file" 2>/dev/null || true +} + +# Search for similar patterns in codebase +function find_duplicates() { + local patterns=$1 + local current_file=$2 + local duplicates="" + + while IFS= read -r pattern; then + if [ -z "$pattern" ]; then + continue + fi + + # Extract just the name + name=$(echo "$pattern" | awk '{print $NF}') + + # Search for similar names in other files + matches=$(rg "\\b$name\\b" --files-with-matches --glob '!node_modules' --glob '!dist' --glob '!build' . 2>/dev/null | grep -v "$current_file" || true) + + if [ -n "$matches" ]; then + duplicates="${duplicates}\n- '$name' also found in: $(echo "$matches" | head -3 | tr '\n' ',' | sed 's/,$//')" + fi + done <<< "$patterns" + + echo -e "$duplicates" +} + +# Run detection +patterns=$(extract_patterns "$file_path") + +if [ -n "$patterns" ]; then + duplicates=$(find_duplicates "$patterns" "$file_path") + + if [ -n "$duplicates" ] && [ "$duplicates" != "" ]; then + echo '{"feedback": "⚠️ Potential duplicates detected:"}' >&2 + echo "$duplicates" | grep -v '^$' | head -5 >&2 + echo '{"feedback": "Consider reusing existing code instead of duplicating."}' >&2 + fi +fi + +# Non-blocking - always succeed +exit 0 diff --git a/.claude/hooks/format-check.sh b/.claude/hooks/format-check.sh new file mode 100755 index 0000000..4ca0478 --- /dev/null +++ b/.claude/hooks/format-check.sh @@ -0,0 +1,16 @@ +#!/bin/bash +# Auto-format JS/TS files with Prettier +set -euo pipefail + +if [[ "$CLAUDE_TOOL_INPUT_FILE_PATH" =~ \.(js|jsx|ts|tsx)$ ]]; then + file_path="${CLAUDE_TOOL_INPUT_FILE_PATH}" + # Use prettier (swap for biome if preferred) + npx prettier --write "$file_path" 2>&1 + exit_code=$? + if [ $exit_code -ne 0 ]; then + echo '{"feedback": "Formatting failed. Check file for syntax errors."}' >&2 + exit 1 + else + echo '{"feedback": "Formatting applied.", "suppressOutput": true}' + fi +fi diff --git a/.claude/hooks/main-branch-protection.sh b/.claude/hooks/main-branch-protection.sh new file mode 100755 index 0000000..1c4c738 --- /dev/null +++ b/.claude/hooks/main-branch-protection.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# Prevent editing on main branch +set -euo pipefail + +current_branch=$(git branch --show-current) +if [ "$current_branch" = "main" ]; then + echo '{"block": true, "message": "Cannot edit files on main branch. Create a feature branch first."}' >&2 + exit 2 +fi diff --git a/.claude/hooks/npm-install.sh b/.claude/hooks/npm-install.sh new file mode 100755 index 0000000..bb6164e --- /dev/null +++ b/.claude/hooks/npm-install.sh @@ -0,0 +1,11 @@ +#!/bin/bash +# Auto-install dependencies when package.json changes +set -euo pipefail + +if [[ "$CLAUDE_TOOL_INPUT_FILE_PATH" =~ package\.json$ ]]; then + echo '{"feedback": "Installing dependencies..."}' >&2 + npm install >/dev/null 2>&1 && echo '{"feedback": "Dependencies installed.", "suppressOutput": true}' || { + echo '{"feedback": "Failed to install dependencies."}' >&2 + exit 1 + } +fi diff --git a/.claude/hooks/test-runner.sh b/.claude/hooks/test-runner.sh new file mode 100755 index 0000000..6adcf24 --- /dev/null +++ b/.claude/hooks/test-runner.sh @@ -0,0 +1,14 @@ +#!/bin/bash +# Auto-run tests when test files change +set -euo pipefail + +if [[ "$CLAUDE_TOOL_INPUT_FILE_PATH" =~ \.test\.(js|jsx|ts|tsx)$ ]]; then + echo '{"feedback": "Running tests..."}' >&2 + npm test -- --findRelatedTests "${CLAUDE_TOOL_INPUT_FILE_PATH}" --passWithNoTests 2>&1 | tail -30 + exit_code=${PIPESTATUS[0]} + if [ $exit_code -eq 0 ]; then + echo '{"feedback": "Tests passed."}' + else + echo '{"feedback": "Tests failed. See output above."}' >&2 + fi +fi diff --git a/.claude/hooks/type-check.sh b/.claude/hooks/type-check.sh new file mode 100755 index 0000000..3138c5c --- /dev/null +++ b/.claude/hooks/type-check.sh @@ -0,0 +1,20 @@ +#!/bin/bash +# Type-check TypeScript files +set -euo pipefail + +if [[ "$CLAUDE_TOOL_INPUT_FILE_PATH" =~ \.(ts|tsx)$ ]]; then + echo '{"feedback": "Checking TypeScript types..."}' >&2 + output=$(npx tsc --noEmit 2>&1) + exit_code=$? + if [ $exit_code -eq 0 ]; then + echo '{"feedback": "No TypeScript errors.", "suppressOutput": true}' + else + errors=$(echo "$output" | grep -A 2 "error TS" | head -30) + if [ -n "$errors" ]; then + echo '{"feedback": "TypeScript found type errors:"}' >&2 + echo "$errors" >&2 + fi + fi + # Non-blocking + exit 0 +fi diff --git a/.claude/settings.json b/.claude/settings.json index 976575d..0c59dda 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -23,7 +23,7 @@ "hooks": [ { "type": "command", - "command": "# Prevent editing on main branch\n[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit files on main branch. Create a feature branch first.\"}' >&2; exit 2; }", + "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/main-branch-protection.sh", "timeout": 5 } ] @@ -35,7 +35,7 @@ "hooks": [ { "type": "command", - "command": "# Auto-format JS/TS files with Prettier (or Biome)\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ \\.(js|jsx|ts|tsx)$ ]]; then\n file_path=\"${CLAUDE_TOOL_INPUT_FILE_PATH}\"\n # Use prettier (swap for biome if preferred)\n npx prettier --write \"$file_path\" 2>&1\n exit_code=$?\n if [ $exit_code -ne 0 ]; then\n echo '{\"feedback\": \"Formatting failed. Check file for syntax errors.\"}' >&2\n exit 1\n else\n echo '{\"feedback\": \"Formatting applied.\", \"suppressOutput\": true}'\n fi\nfi", + "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-check.sh", "timeout": 30 } ] @@ -45,7 +45,7 @@ "hooks": [ { "type": "command", - "command": "# Auto-install dependencies when package.json changes\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ package\\.json$ ]]; then\n echo '{\"feedback\": \"Installing dependencies...\"}' >&2\n npm install >/dev/null 2>&1 && echo '{\"feedback\": \"Dependencies installed.\", \"suppressOutput\": true}' || {\n echo '{\"feedback\": \"Failed to install dependencies.\"}' >&2\n exit 1\n }\nfi", + "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/npm-install.sh", "timeout": 60 } ] @@ -55,7 +55,7 @@ "hooks": [ { "type": "command", - "command": "# Auto-run tests when test files change\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ \\.test\\.(js|jsx|ts|tsx)$ ]]; then\n echo '{\"feedback\": \"Running tests...\"}' >&2\n npm test -- --findRelatedTests \"${CLAUDE_TOOL_INPUT_FILE_PATH}\" --passWithNoTests 2>&1 | tail -30\n exit_code=${PIPESTATUS[0]}\n if [ $exit_code -eq 0 ]; then\n echo '{\"feedback\": \"Tests passed.\"}'\n else\n echo '{\"feedback\": \"Tests failed. See output above.\"}' >&2\n fi\nfi", + "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/test-runner.sh", "timeout": 90 } ] @@ -65,10 +65,20 @@ "hooks": [ { "type": "command", - "command": "# Type-check TypeScript files\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ \\.(ts|tsx)$ ]]; then\n echo '{\"feedback\": \"Checking TypeScript types...\"}' >&2\n output=$(npx tsc --noEmit 2>&1)\n exit_code=$?\n if [ $exit_code -eq 0 ]; then\n echo '{\"feedback\": \"No TypeScript errors.\", \"suppressOutput\": true}'\n else\n errors=$(echo \"$output\" | grep -A 2 \"error TS\" | head -30)\n if [ -n \"$errors\" ]; then\n echo '{\"feedback\": \"TypeScript found type errors:\"}' >&2\n echo \"$errors\" >&2\n fi\n fi\n # Non-blocking\n exit 0\nfi", + "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/type-check.sh", "timeout": 30 } ] + }, + { + "matcher": "Edit|MultiEdit|Write", + "hooks": [ + { + "type": "command", + "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/duplicate-detector.sh", + "timeout": 15 + } + ] } ] } diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index eac5190..f11ee35 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -5,7 +5,10 @@ "ghcr.io/devcontainers/features/docker-in-docker:2": {}, "ghcr.io/devcontainers/features/git:1": {}, "ghcr.io/devcontainers/features/github-cli:1": {}, - "ghcr.io/devcontainers-contrib/features/curl-apt-get:1": {} + "ghcr.io/devcontainers-contrib/features/curl-apt-get:1": {}, + "ghcr.io/devcontainers-contrib/features/playwright:1": { + "browsers": "chromium" + } }, "forwardPorts": [3000, 8080, 8081, 8384, 11434], "portsAttributes": { @@ -45,7 +48,8 @@ "eamodio.gitlens", "bradlc.vscode-tailwindcss", "ZixuanChen.vitest-explorer", - "ms-azuretools.vscode-docker" + "ms-azuretools.vscode-docker", + "ms-playwright.playwright" ], "settings": { "editor.formatOnSave": true, @@ -84,7 +88,9 @@ "NODE_ENV": "development", "OLLAMA_HOST": "http://localhost:11434", "SEARXNG_HOST": "http://localhost:8080", - "SURREALDB_HOST": "http://localhost:8081" + "SURREALDB_HOST": "http://localhost:8081", + "PLAYWRIGHT_HEADLESS": "true", + "PLAYWRIGHT_BROWSER": "chromium" }, "containerEnv": { "TZ": "UTC" diff --git a/.env.example b/.env.example index 844d31b..433d654 100644 --- a/.env.example +++ b/.env.example @@ -23,6 +23,10 @@ SEARXNG_SECRET_KEY=generate-a-random-secret-key-here # Ollama Configuration (Docker local) OLLAMA_HOST=http://localhost:11434 +# Playwright MCP Configuration +PLAYWRIGHT_HEADLESS=true +PLAYWRIGHT_BROWSER=chromium + # Sentry Configuration (optional) SENTRY_AUTH_TOKEN=your-sentry-auth-token SENTRY_ORG=your-sentry-org diff --git a/.github/workflows/pr-claude-code-review.yml b/.github/workflows/pr-claude-code-review.yml index d38127a..0f27ec7 100644 --- a/.github/workflows/pr-claude-code-review.yml +++ b/.github/workflows/pr-claude-code-review.yml @@ -62,7 +62,15 @@ jobs: echo "base_ref=$BASE_REF" >> $GITHUB_OUTPUT fi - - name: Claude Code Review + - name: Setup Python for Serena + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Serena + run: pip install serena-agent + + - name: Claude Code Review with MCP uses: anthropics/claude-code-action@beta with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} @@ -70,12 +78,108 @@ jobs: timeout_minutes: 30 track_progress: true prompt: | - Review this Pull Request using the standards in .claude/agents/code-reviewer.md + # Pull Request Code Review with Enhanced Tools + + You are reviewing this Pull Request with access to advanced MCP tools: + - **Serena**: For deep code analysis and pattern detection + - **Context7**: For up-to-date framework/library documentation + - **GitHub**: For PR information and commenting + + ## Review Process + + ### 1. Read Review Standards + Read `.claude/agents/code-reviewer.md` for the complete review checklist. + + ### 2. Analyze Changes + ```bash + # Get PR diff + git diff origin/${{ steps.pr-info.outputs.base_ref }}...HEAD + + # Get changed files list + git diff --name-only origin/${{ steps.pr-info.outputs.base_ref }}...HEAD + ``` + + ### 3. Use Serena for Deep Analysis + - Analyze code quality patterns in changed files + - Identify potential issues and anti-patterns + - Get recommendations for improvements + - Check for code smells and technical debt + + ### 4. Use Context7 for Best Practices + When reviewing specific technologies: + - React code → Query Context7 for latest React patterns + - TypeScript → Check TypeScript best practices + - Libraries used → Get current documentation and usage patterns + - Security concerns → Reference OWASP guidelines + + ### 5. Apply Review Checklist + For each changed file, verify: + + **TypeScript Quality**: + - [ ] No `any` types without justification + - [ ] Proper type narrowing and guards + - [ ] Interface definitions for complex objects + - [ ] Generic types used appropriately - 1. Read .claude/agents/code-reviewer.md for the full checklist - 2. Run `git diff origin/${{ steps.pr-info.outputs.base_ref }}...HEAD` to see changes - 3. Apply the review checklist to modified files - 4. Provide feedback organized by severity (Critical, Warning, Suggestion) + **React Patterns** (if applicable): + - [ ] Hooks used correctly (no violations of rules) + - [ ] Proper dependency arrays + - [ ] Appropriate memoization (not over-used) + - [ ] Loading/error/empty states handled + + **Security**: + - [ ] User input sanitized + - [ ] No injection vulnerabilities + - [ ] Authentication/authorization checked + - [ ] Sensitive data not exposed + + **Testing**: + - [ ] Tests included for new features + - [ ] Edge cases covered + - [ ] Tests follow TDD patterns + + ### 6. Provide Structured Feedback + + Post review comment organized by severity: + + **🔴 Critical Issues** (must fix before merge): + - Security vulnerabilities + - Breaking changes + - Data loss risks + + **🟡 Warnings** (should fix): + - Type errors + - Poor error handling + - Performance issues + - Missing tests + + **🟢 Suggestions** (nice to have): + - Code style improvements + - Better naming + - Refactoring opportunities + + **✅ Positive Notes**: + - Good patterns used + - Well-tested code + - Clear documentation + + ### 7. Add Specific File Comments + For critical/warning issues, use: + ```bash + gh pr comment ${{ github.event.pull_request.number || github.event.issue.number }} --body "" + ``` + + ## Guidelines + - Be constructive and helpful + - Reference specific lines/files + - Explain WHY something is an issue + - Suggest concrete fixes + - Use MCP tools to back up recommendations + - Focus on objective quality, not subjective style claude_args: | - --max-turns 10 - --allowedTools "Read,Glob,Grep,Bash(git:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)" + --max-turns 15 + --allowedTools "Read,Glob,Grep,Bash(git:*),Bash(gh:*)" + env: + SERENA_API_KEY: ${{ secrets.SERENA_API_KEY }} + SERENA_HOST: ${{ secrets.SERENA_HOST || 'http://localhost:8384' }} + CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }} diff --git a/.github/workflows/scheduled-claude-auto-improvement.yml b/.github/workflows/scheduled-claude-auto-improvement.yml new file mode 100644 index 0000000..35d34bc --- /dev/null +++ b/.github/workflows/scheduled-claude-auto-improvement.yml @@ -0,0 +1,228 @@ +name: Scheduled - Auto Improvement + +on: + schedule: + # Run every Monday at 9 AM UTC + - cron: '0 9 * * 1' + workflow_dispatch: + inputs: + focus_area: + description: 'Focus area for improvement (docs, tests, performance, security, types)' + required: false + default: 'auto' + create_pr: + description: 'Create PR for improvements' + required: false + default: 'true' + +concurrency: + group: ${{ github.workflow }}-${{ github.run_id }} + cancel-in-progress: false + +permissions: + contents: write + pull-requests: write + issues: write + +jobs: + analyze-and-improve: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Setup Python for Serena + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Serena + run: pip install serena-agent + + - name: Generate branch name + id: branch + run: | + FOCUS="${{ github.event.inputs.focus_area || 'auto' }}" + BRANCH_NAME="claude/auto-improvement-${FOCUS}-$(date +%Y%m%d-%H%M)" + echo "name=$BRANCH_NAME" >> $GITHUB_OUTPUT + + - name: Claude Auto Improvement + uses: anthropics/claude-code-action@beta + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + model: claude-opus-4-5-20251101 + timeout_minutes: 60 + base_branch: main + branch_prefix: claude/auto-improvement- + track_progress: true + prompt: | + # Weekly Auto-Improvement Task + + You are an autonomous code improvement agent. Your goal is to analyze the codebase, identify improvement opportunities, and implement fixes. + + ## Available Tools & Integrations + + You have access to: + - **Serena MCP**: Code analysis and review insights + - **Context7 MCP**: Up-to-date documentation for libraries/frameworks + - **Ollama**: Local LLM for duplicate detection and code analysis + - **Standard tools**: Read, Write, Edit, Glob, Grep, Bash + + ## Focus Area + **${{ github.event.inputs.focus_area || 'Auto-detect based on recent changes' }}** + + ## Your Mission + + ### Step 1: Analyze Recent Changes + ```bash + # Get recent commits to identify active areas + git log --since="7 days ago" --name-only --pretty=format: | sort -u + + # Identify frequently changed files + git log --since="30 days ago" --format=format: --name-only | sort | uniq -c | sort -rn | head -20 + ``` + + ### Step 2: Use Serena for Code Review Insights + - Use Serena MCP to analyze code quality patterns + - Identify common issues across the codebase + - Get recommendations for improvements + - Focus on frequently changed files (they need the most attention) + + ### Step 3: Determine Focus Area (if auto) + Based on analysis, choose one focus area: + - **Documentation**: Missing/outdated docs, unclear function descriptions + - **Tests**: Low coverage, missing edge cases, brittle tests + - **Performance**: Unnecessary re-renders, large bundles, slow queries + - **Security**: Input validation, authentication issues, XSS/injection risks + - **Types**: TypeScript any types, missing interfaces, poor type safety + - **Code Quality**: Duplicate code, complex functions, poor naming + + ### Step 4: Use Context7 for Reference + For the chosen focus area: + - Use Context7 to get latest best practices + - Look up documentation for key libraries (React, TypeScript, etc.) + - Reference current patterns and recommended approaches + + ### Step 5: Implement Improvements + Based on your analysis: + + **For Documentation**: + - Add JSDoc comments to complex functions + - Update README if outdated + - Add inline comments for non-obvious logic + + **For Tests**: + - Add missing test cases + - Improve test descriptions + - Add edge case coverage + - Fix brittle tests + + **For Performance**: + - Add React.memo where beneficial + - Optimize expensive calculations with useMemo + - Implement virtualization for long lists + - Code-split large bundles + + **For Security**: + - Add input sanitization + - Fix potential XSS vulnerabilities + - Validate API inputs + - Remove hardcoded secrets + + **For Types**: + - Replace `any` with proper types + - Add missing interface definitions + - Improve type narrowing + - Fix implicit any + + **For Code Quality**: + - Extract duplicate code into utilities + - Simplify complex functions + - Improve variable naming + - Reduce nesting levels + + ### Step 6: Verify Changes + Run checks to ensure improvements don't break anything: + ```bash + npm run lint + npm run typecheck + npm test + ``` + + Fix any issues before proceeding. + + ### Step 7: Create PR (if improvements made) + If you made improvements: + - Commit with format: `chore(improvement): - ` + - Create PR with detailed description of improvements + - Include metrics (files changed, issues fixed, etc.) + - Add appropriate labels + + ## Guidelines + + - **Be autonomous**: Don't ask for permission, make improvements + - **Be conservative**: Only change what clearly needs improvement + - **Be thorough**: Test changes before committing + - **Be focused**: Stick to one area, don't try to fix everything + - **Use MCP tools**: Leverage Serena and Context7 for better insights + - **Document reasoning**: Explain why each change improves the code + + ## Success Criteria + + - At least 5 meaningful improvements made + - All checks passing (lint, types, tests) + - Clear PR description with rationale + - No breaking changes introduced + + If no improvements are needed, create an issue documenting that the codebase is in good shape. + claude_args: | + --max-turns 50 + --allowedTools "Read,Write,Edit,Glob,Grep,Bash(git:*),Bash(gh:*),Bash(npm:*),Bash(npx:*)" + env: + SERENA_API_KEY: ${{ secrets.SERENA_API_KEY }} + SERENA_HOST: ${{ secrets.SERENA_HOST || 'http://localhost:8384' }} + CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }} + OLLAMA_HOST: http://localhost:11434 + + - name: Summary Report + if: always() + run: | + echo "## Auto-Improvement Run Complete" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "**Focus Area**: ${{ github.event.inputs.focus_area || 'Auto-detect' }}" >> $GITHUB_STEP_SUMMARY + echo "**Branch**: ${{ steps.branch.outputs.name }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Check for PRs or issues created by this workflow." >> $GITHUB_STEP_SUMMARY + + notify-on-failure: + needs: analyze-and-improve + if: failure() + runs-on: ubuntu-latest + steps: + - name: Create issue on failure + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: '🤖 Auto-improvement workflow failed', + body: `The weekly auto-improvement workflow failed. + + **Workflow Run**: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId} + **Branch**: \`${{ steps.branch.outputs.name }}\` + + Please investigate and fix the issue.`, + labels: ['automation', 'bug'] + }) diff --git a/.mcp.json b/.mcp.json index dd965a5..9095cad 100644 --- a/.mcp.json +++ b/.mcp.json @@ -82,6 +82,16 @@ "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-memory"] + }, + + "playwright": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@executeautomation/playwright-mcp-server"], + "env": { + "PLAYWRIGHT_HEADLESS": "${PLAYWRIGHT_HEADLESS:-true}", + "PLAYWRIGHT_BROWSER": "${PLAYWRIGHT_BROWSER:-chromium}" + } } } }