{"id":40411638,"url":"https://github.com/tomblancdev/professor-oak","last_synced_at":"2026-01-20T14:09:24.205Z","repository":{"id":332414367,"uuid":"1132089114","full_name":"tomblancdev/professor-oak","owner":"tomblancdev","description":"Gamified learning system with Pokemon-themed progress tracking","archived":false,"fork":false,"pushed_at":"2026-01-13T20:19:42.000Z","size":285,"stargazers_count":0,"open_issues_count":23,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T20:26:18.684Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomblancdev.png","metadata":{"files":{"readme":".github/README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T09:57:32.000Z","updated_at":"2026-01-13T20:01:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tomblancdev/professor-oak","commit_stats":null,"previous_names":["tomblancdev/professor-oak"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tomblancdev/professor-oak","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomblancdev%2Fprofessor-oak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomblancdev%2Fprofessor-oak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomblancdev%2Fprofessor-oak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomblancdev%2Fprofessor-oak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomblancdev","download_url":"https://codeload.github.com/tomblancdev/professor-oak/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomblancdev%2Fprofessor-oak/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28604712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T12:01:53.233Z","status":"ssl_error","status_checked_at":"2026-01-20T12:01:46.545Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T14:09:23.392Z","updated_at":"2026-01-20T14:09:24.197Z","avatar_url":"https://github.com/tomblancdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CI/CD Pipeline Documentation\n\nThis directory contains the AI-enhanced CI/CD workflows for the Professor Oak project.\n\n## Workflows\n\n### 1. CI (`ci.yml`)\n\n**Triggers:** Push to main/develop, Pull Requests\n\n**Jobs:**\n- **Build \u0026 Test**: Uses devcontainers to build and test the MCP server\n- **Lint**: TypeScript type checking\n- **Security Scan**: npm audit + TruffleHog secret detection\n\n**Tech Stack:**\n- DevContainers CI action for consistent build environments\n- Vitest for testing\n- TruffleHog for secret scanning\n\n### 2. AI-Powered PR Review (`pr-review.yml`)\n\n**Triggers:** PR opened/updated, Comments with @claude\n\n**Jobs:**\n- **Claude Code Review**: AI-powered code review using Anthropic's Claude\n  - MCP server best practices validation\n  - TypeScript quality checks\n  - Security analysis\n  - Testing coverage validation\n  - Documentation completeness\n\n- **Test Coverage Report**: Automated coverage reporting on PRs\n- **Build Check**: Validates build artifacts\n\n**Special Features:**\n- Responds to @claude mentions in PR comments\n- Context-aware reviews focused on MCP server patterns\n- Constructive, actionable feedback\n\n### 3. CodeQL Security Scan (`codeql.yml`)\n\n**Triggers:** Push, PR, Weekly schedule (Sundays 3 AM UTC)\n\n**Features:**\n- Static analysis for security vulnerabilities\n- JavaScript/TypeScript code scanning\n- Extended security queries\n- Automated weekly scans\n\n### 4. Dependabot (`dependabot.yml`)\n\n**Configuration:**\n- **npm**: Weekly updates for MCP server dependencies\n- **GitHub Actions**: Weekly updates for workflow actions\n- **Docker**: Weekly updates for base images\n\n**Settings:**\n- Runs every Monday at 9 AM UTC\n- Automatic PR creation with labels\n- Conventional commit messages\n\n### 5. Release (`release.yml`)\n\n**Triggers:** Version tags (v*.*.*)\n\n**Jobs:**\n- **Create Release**: Automated changelog generation\n- **Build Docker**: Multi-platform Docker image build and publish to GHCR\n\n**Outputs:**\n- GitHub Release with changelog\n- Docker image: `ghcr.io/tomblancdev/professor-oak`\n- Tags: version, major.minor, major, latest\n\n## Setup Requirements\n\n### Secrets\n\nAdd these secrets to your repository settings:\n\n1. **ANTHROPIC_API_KEY** (Required for AI code review)\n   - Get from: https://console.anthropic.com/\n   - Permissions: API key with access to Claude Sonnet 4.5\n\n2. **GITHUB_TOKEN** (Automatically provided)\n   - Used for GitHub API interactions\n\n### Repository Settings\n\n1. Enable GitHub Actions:\n   - Settings → Actions → General → Allow all actions\n\n2. Enable GitHub Container Registry:\n   - Settings → Packages → Enable packages\n\n3. Branch Protection Rules (Recommended):\n   ```\n   Branch: main\n   - Require status checks to pass before merging\n     ✓ Build \u0026 Test (MCP Server)\n     ✓ Lint Check\n     ✓ Build Status\n   - Require pull request reviews before merging\n   - Require conversation resolution before merging\n   ```\n\n## Using the AI Code Review\n\n### Automatic Review\n\nThe AI reviewer runs automatically on all PRs, analyzing:\n- Code quality and TypeScript best practices\n- MCP server patterns (tool descriptions, error handling, etc.)\n- Security vulnerabilities\n- Test coverage\n\n### Interactive Review\n\nComment on any PR with:\n```\n@claude review this code for security issues\n```\n\nThe AI will respond with targeted analysis based on your request.\n\n### Review Focus Areas\n\nThe AI reviewer is specifically trained to check:\n\n1. **MCP Server Patterns**\n   - Tool descriptions teach AI when to use tools\n   - Structured JSON responses\n   - Idempotent operations\n   - Proper Zod schema validation\n\n2. **Security**\n   - No hardcoded secrets\n   - Input validation\n   - File path sanitization\n   - Environment variable usage\n\n3. **TypeScript Quality**\n   - Type safety\n   - Avoiding 'any' types\n   - Async/await error handling\n\n4. **Testing**\n   - Test coverage for new features\n   - Edge case handling\n   - Proper mocking\n\n## Workflow Customization\n\n### Changing AI Model\n\nEdit `pr-review.yml`:\n```yaml\nmodel: claude-opus-4-5-20251101  # For more powerful reviews\n```\n\n### Adjusting Dependabot Frequency\n\nEdit `dependabot.yml`:\n```yaml\nschedule:\n  interval: \"daily\"  # or \"monthly\"\n```\n\n### Adding More CI Checks\n\nAdd steps to `ci.yml`:\n```yaml\n- name: Custom Check\n  run: npm run custom-script\n```\n\n## CI/CD Best Practices Applied\n\nBased on 2025 MCP and GitHub Actions best practices:\n\n1. **Container-First Approach**: All builds use devcontainers for consistency\n2. **Semantic Versioning**: Automated via release tags\n3. **Security as Code**: TruffleHog, CodeQL, npm audit\n4. **AI-Powered Reviews**: Claude Code for context-aware feedback\n5. **Idempotent Workflows**: Can be re-run safely\n6. **Observability**: Test results, coverage reports, build artifacts\n7. **Automated Dependencies**: Dependabot for security patches\n\n## Monitoring \u0026 Debugging\n\n### View Workflow Runs\n- Actions tab → Select workflow → View logs\n\n### Debug Failed Builds\n```bash\n# Run locally with same devcontainer\ncd mcp/professor-oak-mcp\ndocker compose up\n```\n\n### Test Coverage Locally\n```bash\ncd mcp/professor-oak-mcp\nnpm run test:run -- --coverage\n```\n\n## Resources\n\n- [Claude Code GitHub Actions Docs](https://code.claude.com/docs/en/github-actions)\n- [DevContainers CI](https://github.com/devcontainers/ci)\n- [MCP Best Practices](https://modelcontextprotocol.info/docs/best-practices/)\n- [GitHub Actions Documentation](https://docs.github.com/en/actions)\n\n## Troubleshooting\n\n### AI Review Not Running\n\n1. Check `ANTHROPIC_API_KEY` is set\n2. Verify GitHub App is installed (if using claude-code-action)\n3. Check workflow permissions in repo settings\n\n### Build Failures\n\n1. Ensure devcontainer.json is valid\n2. Check npm dependencies are locked (package-lock.json)\n3. Verify Docker is available on runner\n\n### Coverage Report Missing\n\n1. Ensure vitest is configured with coverage\n2. Check coverage directory path in workflow\n3. Verify tests are actually running\n\n---\n\n**Need help?** Open an issue or consult the [learning materials](C:/Users/Tom/learning/claude/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomblancdev%2Fprofessor-oak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomblancdev%2Fprofessor-oak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomblancdev%2Fprofessor-oak/lists"}