diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..34f9012 --- /dev/null +++ b/.env.example @@ -0,0 +1,57 @@ +# ============================================================================= +# Environment Variables Template +# ============================================================================= +# Copy this file to .env.local and fill in the values +# Do NOT commit .env.local to version control +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Application Settings +# ----------------------------------------------------------------------------- + +# Application name displayed in UI +VITE_APP_NAME="AI Models Explorer" + +# API Base URL (optional - defaults to models.dev) +# VITE_API_BASE_URL="https://models.dev" + +# ----------------------------------------------------------------------------- +# Feature Flags +# ----------------------------------------------------------------------------- + +# Enable/disable development features +VITE_ENABLE_DEVTOOLS="true" +VITE_ENABLE_LOGGING="false" + +# ----------------------------------------------------------------------------- +# Analytics (optional) +# ----------------------------------------------------------------------------- + +# VITE_GA_TRACKING_ID="" +# VITE_SENTRY_DSN="" + +# ----------------------------------------------------------------------------- +# API Keys (if needed for external services) +# ----------------------------------------------------------------------------- + +# Note: API keys for services like OpenAI, Anthropic, etc. +# should be server-side only and not exposed in client code +# These would be used in server functions only + +# ----------------------------------------------------------------------------- +# Netlify-specific (set in Netlify dashboard, not here) +# ----------------------------------------------------------------------------- +# The following variables are set in Netlify dashboard: +# - NETLIFY_AUTH_TOKEN +# - NETLIFY_SITE_ID +# - API_SECRET_KEYS (if needed) + +# ----------------------------------------------------------------------------- +# Build-time Configuration +# ----------------------------------------------------------------------------- + +# Skip demo route linting errors during build +# SKIP_DEMO_LINT=true + +# Node.js environment +# NODE_ENV=production diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..a7ea16a --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,145 @@ +name: CI + +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + +env: + NODE_VERSION: '20' + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run linting + run: npm run lint + + - name: Check formatting + run: npm run format -- --check + + type-check: + name: Type Check + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run type checking + run: npx tsc --noEmit + + test: + name: Test + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run tests + run: npm run test + + build: + name: Build + runs-on: ubuntu-latest + needs: [lint, type-check, test] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Build application + run: npm run build + env: + # Skip demo routes linting errors as per project conventions + SKIP_DEMO_LINT: true + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: build-output + path: dist/ + retention-days: 7 + + # Matrix build for multiple Node.js versions + matrix-build: + name: Build (Node.js ${{ matrix.node-version }}) + runs-on: ubuntu-latest + strategy: + matrix: + node-version: ['18', '20', '22'] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Build application + run: npm run build + + notify: + name: Notify + runs-on: ubuntu-latest + needs: [lint, type-check, test, build] + if: always() + steps: + - name: Check job status + run: | + if [ "${{ needs.lint.result }}" == "failure" ] || \ + [ "${{ needs.type-check.result }}" == "failure" ] || \ + [ "${{ needs.test.result }}" == "failure" ] || \ + [ "${{ needs.build.result }}" == "failure" ]; then + echo "CI_FAILED=true" >> $GITHUB_ENV + else + echo "CI_FAILED=false" >> $GITHUB_ENV + fi + + - name: Send failure notification + if: env.CI_FAILED == 'true' + run: echo "CI failed - check GitHub Actions for details" diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100644 index 0000000..2312dc5 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1 @@ +npx lint-staged diff --git a/.netlify/state.json b/.netlify/state.json index 1ee633e..d6419b7 100644 --- a/.netlify/state.json +++ b/.netlify/state.json @@ -15,6 +15,6 @@ "longitude": 107.6084, "postalCode": "40287" }, - "timestamp": 1767168556068 + "timestamp": 1767259757151 } } \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 1274732..c31e69b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,114 +8,27 @@ Context for agentic coding systems working on this project. - When you have zero context about this project, just read `docs/spec/models-explorer.MD` (beware: large document) and `docs/implementation-phases.md` - Never try to start dev server, dev server always running at `http://localhost:3000` -## Subagents and Skills - -### Built-in Tools - -Leverate built-in tools if you have the necessary permissions. - -- **bash**: Execute shell commands in your project environment. -- **edit**: Modify existing files using exact string replacements. -- **write**: Create new files or overwrite existing ones. -- **read**: Read file contents from your codebase. -- **grep**: Search file contents using regular expressions. -- **glob**: Find files by pattern matching. -- **list**: List files and directories in a given path. -- **patch**: Apply patches to files. -- **skill**: Load a skill (a SKILL.md file) and return its content in the conversation. -- **task**: Launch a new agent to handle complex, multi-step tasks autonomously. -- **todowrite**: Manage todo lists during coding sessions. -- **todoread**: Read existing todo lists. -- **webfetch**: Fetch web content. -- **websearch**: Search necessary information on the web. -- **codesearch**: Search real-world codebases for relevant examples. -- **batch**: Executes multiple independent tool calls concurrently to reduce latency. -- **gh_grep**: Search real-world code examples from GitHub -- **context7**: Fetch up-to-date documentation for libraries -- **playwright**: UI testing (when applicable) +--- + +## Specialist Agent Usage -### Specialists / Subagents +### When to Invoke Specialists -- **github-flow**: creating branches for new features or bug fixes, making commits with clear and concise messages, opening pull requests for code review, and merging changes after approval. -- **builder**: To implement the code +- **explore**: For exploring codebase and understanding its structure - **researcher**: For gathering documentation, examples, or best practices -- **qa-specialist**: To perform quality assurance (QA) tasks, such as testing software, identifying defects, or verifying functionality. +- **builder**: For implementing features, fixing bugs, or making code changes - **code-reviewer**: To review code and provide feedback. -- **technical-writer**: For adding, updating, or fixing documentation - -## Quality Gates - -Each feature must pass through these checkpoints before merging: - -### Gate 1: Requirements Ready ☐ -- [ ] Clear user requirements documented -- [ ] Definition of Done specified -- [ ] Tech constraints identified -- [ ] Branch created via `@github-flow` - -### Gate 2: Design Complete ☐ -- [ ] Implementation plan created -- [ ] Relevant files explored -- [ ] Research documented (if needed) -- [ ] Dependencies identified - -### Gate 3: Implementation Ready ☐ -- [ ] Context files provided to `@builder` -- [ ] Technical specifications clear -- [ ] Testing approach defined - -### Gate 4: Code Complete ☐ -- [ ] Code written -- [ ] Passes linting (`npm run check`) -- [ ] Follows project patterns -- [ ] Self-reviewed - -### Gate 5: Review Complete ☐ -- [ ] `@code-reviewer` approved -- [ ] Issues addressed -- [ ] Changes committed - -### Gate 6: Testing Complete ☐ -- [ ] `@qa-specialist` verified -- [ ] Tests pass (`npm run test`) -- [ ] No critical bugs - -### Gate 7: Ready for Merge ☐ -- [ ] PR created with clear description -- [ ] Documentation updated (if needed) -- [ ] Approved for merge +- **qa-specialist**: Audit code, verifies file structures, and runs tests +- **git-manager**: creating branches for new features or bug fixes, making commits with clear and concise messages, opening pull requests for code review, and merging changes after approval. +- **doc-writer**: For adding, updating, or fixing documentation -## Testing Strategy - -### QA Involvement Points +### 3rd Party Tool Usage Guidelines -1. **Before Implementation**: Test plan creation -2. **During Implementation**: Component-level testing -3. **After Implementation**: Integration testing -4. **Before PR**: Full regression testing - -### Test Coverage Requirements - -| Scenario | Coverage | -|----------|----------| -| Critical paths (authentication, data loading) | 100% | -| New features | 80%+ | -| Bug fixes | Specific scenario tests | -| Refactoring | Existing tests still pass | - -## Documentation Requirements - -### When Documentation is Required - -Document must concise and clear. +- **gh_grep**: Search real-world code examples from GitHub +- **context7**: Fetch up-to-date documentation for libraries +- **playwright**: UI testing (when applicable) -| Change | Documentation Needed | -|--------|---------------------| -| New feature | Feature doc + API changes | -| Bug fix | Issue resolution doc | -| Breaking change | Migration guide | -| New component | Component usage doc | -| Complex logic | In-code comments + architecture doc | +--- ## Tech Stack @@ -225,6 +138,93 @@ src/ --- +## Quality Gates + +Each feature must pass through these checkpoints before merging: + +### Gate 1: Requirements Ready ☐ + +- [ ] Clear user requirements documented +- [ ] Definition of Done specified +- [ ] Tech constraints identified +- [ ] Branch created via `@git-flow` + +### Gate 2: Design Complete ☐ + +- [ ] Implementation plan created +- [ ] Relevant files explored +- [ ] Research documented (if needed) +- [ ] Dependencies identified + +### Gate 3: Implementation Ready ☐ + +- [ ] Context files provided to `@builder` +- [ ] Technical specifications clear +- [ ] Testing approach defined + +### Gate 4: Code Complete ☐ + +- [ ] Code written +- [ ] Passes linting (`npm run check`) +- [ ] Follows project patterns +- [ ] Self-reviewed + +### Gate 5: Review Complete ☐ + +- [ ] `@code-reviewer` approved +- [ ] Issues addressed +- [ ] Changes committed + +### Gate 6: Testing Complete ☐ + +- [ ] `@qa-specialist` verified +- [ ] Tests pass (`npm run test`) +- [ ] No critical bugs + +### Gate 7: Ready for Merge ☐ + +- [ ] PR created with clear description +- [ ] Documentation updated (if needed) +- [ ] Approved for merge + +--- + +## Testing Strategy + +### QA Involvement Points + +1. **Before Implementation**: Test plan creation +2. **During Implementation**: Component-level testing +3. **After Implementation**: Integration testing +4. **Before PR**: Full regression testing + +### Test Coverage Requirements + +| Scenario | Coverage | +| --------------------------------------------- | ------------------------- | +| Critical paths (authentication, data loading) | 100% | +| New features | 80%+ | +| Bug fixes | Specific scenario tests | +| Refactoring | Existing tests still pass | + +--- + +## Documentation Requirements + +### When Documentation is Required + +Document must concise and clear. + +| Change | Documentation Needed | +| --------------- | ----------------------------------- | +| New feature | Feature doc + API changes | +| Bug fix | Issue resolution doc | +| Breaking change | Migration guide | +| New component | Component usage doc | +| Complex logic | In-code comments + architecture doc | + +--- + ## Demo Files Demo files under `src/routes/demo` use it as guide, skip the linter error. diff --git a/docs/ci-cd-setup.md b/docs/ci-cd-setup.md new file mode 100644 index 0000000..f6a8bf1 --- /dev/null +++ b/docs/ci-cd-setup.md @@ -0,0 +1,613 @@ +# CI/CD Setup Guide + +**Version:** 1.0.0 +**Last Updated:** 2026-01-01 +**Project:** AI Models Explorer (TanStack Start) + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [GitHub Actions CI Setup](#github-actions-ci-setup) +3. [Netlify Deploy Configuration](#netlify-deploy-configuration) +4. [Pre-commit Hooks with Husky](#pre-commit-hooks-with-husky) +5. [Deployment Workflow](#deployment-workflow) +6. [Environment Variables](#environment-variables) +7. [Quality Gates](#quality-gates) +8. [Troubleshooting](#troubleshooting) + +--- + +## 1. Overview + +### What is CI/CD + +**CI (Continuous Integration)** is a development practice where developers integrate code into a shared repository frequently, preferably several times a day. Each integration is verified by an automated build and tests to detect errors quickly. + +**CD (Continuous Deployment/Delivery)** extends CI by automatically deploying all code changes to a production or staging environment after the build and tests pass. + +### Why CI/CD is Needed + +| Benefit | Description | +| ------------------------- | ------------------------------------------------------- | +| **Early Bug Detection** | Automated tests catch bugs before they reach production | +| **Consistent Quality** | Linting and type checking ensure code standards | +| **Faster Feedback** | Developers get immediate feedback on changes | +| **Reduced Manual Effort** | Automated deployments eliminate manual steps | +| **Reliable Releases** | Consistent build process reduces deployment failures | +| **Collaboration** | Status checks enable better code review processes | + +### Current Setup + +This project uses **Netlify** for deployment with **GitHub Actions** for CI/CD: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Development │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Commit │───▶│ Push to │───▶│ GitHub │───▶│ CI/CD │ │ +│ │ Code │ │ GitHub │ │ Actions │ │ Pipeline│ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Netlify │◀───│ Deploy │◀───│ Status │◀───│ Build │ │ +│ │ CDN │ │ Preview │ │ Checks │ │ & Test │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. GitHub Actions CI Setup + +### Workflow File + +The CI workflow is defined in `.github/workflows/ci.yml`: + +```yaml +name: CI + +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] +``` + +### Jobs Overview + +| Job | Purpose | Dependencies | +| -------------- | ---------------------------------- | ---------------------- | +| `lint` | Run ESLint and Prettier checks | None | +| `type-check` | TypeScript strict mode checking | None | +| `test` | Run Vitest test suite | None | +| `build` | Build production application | lint, type-check, test | +| `matrix-build` | Build on multiple Node.js versions | None | +| `notify` | Notify on failure/success | All jobs | + +### Trigger Conditions + +The workflow triggers on: + +- **Push** to `main` or `master` branches +- **Pull requests** targeting `main` or `master` branches + +### Caching Strategy + +Dependencies are cached using GitHub Actions cache: + +```yaml +- name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' +``` + +This caches `node_modules` between runs, significantly speeding up CI. + +### Matrix Strategy for Node.js Versions + +The build job runs on multiple Node.js versions to ensure compatibility: + +```yaml +jobs: + matrix-build: + strategy: + matrix: + node-version: ['18', '20', '22'] +``` + +### Required Scripts + +The workflow uses these npm scripts: + +| Script | Command | Purpose | +| ---------------- | ------------ | ---------------- | +| `npm run lint` | `eslint` | Run ESLint | +| `npm run format` | `prettier` | Check formatting | +| `npm run test` | `vitest run` | Run tests | +| `npm run build` | `vite build` | Build production | + +--- + +## 3. Netlify Deploy Configuration + +### Current Configuration + +The `netlify.toml` file is already configured: + +```toml +[build] + command = "vite build" + dir = "dist/client" + +[dev] + command = "npm run dev" + targetPort = 3000 + port = 8888 +``` + +### Build Settings + +| Setting | Value | Description | +| ----------------- | ------------- | ----------------------- | +| Build Command | `vite build` | Vite production build | +| Publish Directory | `dist/client` | Static output directory | +| Node Version | 20 | Match CI configuration | + +### Environment Variables in Netlify + +Set these in **Netlify Dashboard > Site Settings > Environment Variables**: + +| Variable | Value | Purpose | +| ---------------- | ------ | ----------------------- | +| `NODE_VERSION` | `20` | Node.js version | +| `SKIP_DEMO_LINT` | `true` | Skip demo route linting | + +### Redirects (if needed) + +For SPA routing with TanStack Router, add to `netlify.toml`: + +```toml +[[redirects]] + from = "/*" + to = "/index.html" + status = 200 +``` + +--- + +## 4. Pre-commit Hooks with Husky + +### Installation + +```bash +# Install Husky and lint-staged +npm install -D husky lint-staged + +# Initialize Husky +npx husky install + +# Add Husky prepare script to package.json +npm pkg set scripts.prepare="husky install" +``` + +### Configuration + +Add to `package.json`: + +```json +{ + "lint-staged": { + "*.{ts,tsx,js,jsx}": ["npm run lint", "npm run format"], + "*.{json,md,yml,yaml}": ["npm run format"] + } +} +``` + +### Create Pre-commit Hook + +```bash +# Create pre-commit hook +npx husky add .husky/pre-commit "npx lint-staged" +``` + +### Git Hook Flow + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Pre-commit Hook Flow │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. Developer runs `git commit` │ +│ │ +│ 2. Husky triggers pre-commit hook │ +│ │ +│ 3. lint-staged runs on staged files │ +│ ├── ESLint (fixes auto-fixable errors) │ +│ └── Prettier (formats code) │ +│ │ +│ 4. If checks pass: │ +│ ├── Files are staged │ +│ ├── Commit is created │ +│ └── Hook exits successfully │ +│ │ +│ 5. If checks fail: │ +│ ├── Errors are displayed │ +│ ├── Commit is aborted │ +│ └── Developer must fix issues │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Benefits + +- **Local Feedback**: Issues caught before pushing +- **Clean History**: No style violations in commits +- **Fast Iteration**: Quick fixes during development + +--- + +## 5. Deployment Workflow + +### Branch Strategy + +``` +main branch (production) +│ +├── Feature branches (develop features) +│ └── Pull requests with CI checks +│ +├── Develop branch (optional, staging) +│ └── Can deploy to staging environment +│ +└── Hotfix branches (critical fixes) + └── Fast-track to production +``` + +### Deployment Flow + +#### Push to Main + +``` +1. Developer pushes code to main +2. GitHub Actions CI runs + ├── Lint ✓ + ├── Type Check ✓ + ├── Test ✓ + └── Build ✓ +3. Netlify detects change +4. Netlify deploys to production +5. Status check passes on GitHub +``` + +#### Pull Request + +``` +1. Developer opens PR +2. GitHub Actions CI runs + ├── Lint ✓ + ├── Type Check ✓ + ├── Test ✓ + └── Build ✓ +3. Netlify creates preview deployment +4. Preview URL added to PR +5. Reviewers can test changes +6. CI status required for merge +``` + +### Branch Protections + +In **GitHub > Repository > Settings > Branches**: + +1. **Add branch protection rule** for `main` +2. **Require pull request reviews**: 1 approval +3. **Require status checks to pass**: + - `lint` + - `type-check` + - `test` + - `build` +4. **Require conversation resolution** +5. **Restrict who can push** to main (optional) + +--- + +## 6. Environment Variables + +### Variable Categories + +#### Client-side (VITE\_\*) + +These are exposed to the browser and prefixed with `VITE_`: + +| Variable | Example | Purpose | +| ---------------------- | ------------------------- | --------------------- | +| `VITE_APP_NAME` | "AI Models Explorer" | App display name | +| `VITE_API_BASE_URL` | "https://api.example.com" | API endpoint | +| `VITE_ENABLE_DEVTOOLS` | "true" | Enable React DevTools | + +#### Server-side + +Used in server functions only, not exposed to client: + +| Variable | Example | Purpose | +| ---------------- | ------------------ | ------------------- | +| `API_SECRET_KEY` | "sk-..." | API authentication | +| `DATABASE_URL` | "postgresql://..." | Database connection | + +#### Build-time + +Set during build process: + +| Variable | Example | Purpose | +| ---------------- | ------------ | --------------------- | +| `SKIP_DEMO_LINT` | "true" | Skip demo lint errors | +| `NODE_ENV` | "production" | Build mode | + +### Creating Environment Files + +```bash +# Copy template +cp .env.example .env.local + +# Edit with your values +nano .env.local +``` + +### Netlify Environment Variables + +Set in **Netlify Dashboard > Site Settings > Environment Variables**: + +``` +NODE_VERSION=20 +SKIP_DEMO_LINT=true +VITE_APP_NAME=AI Models Explorer +``` + +### GitHub Actions Secrets + +Set in **GitHub > Repository > Settings > Secrets and variables > Actions**: + +| Secret | Purpose | +| -------------------- | ----------------------- | +| `NETLIFY_AUTH_TOKEN` | Netlify API access | +| `NETLIFY_SITE_ID` | Netlify site identifier | + +--- + +## 7. Quality Gates + +### Branch Protection Rules + +Configure in GitHub repository settings: + +#### Required Status Checks + +``` +Required Checks: +├── lint +├── type-check +├── test +└── build +``` + +#### Merge Requirements + +``` +Before merging, require: +├── At least 1 approved review +├── All status checks passed +├── No unresolved conversations +├── Up to date with main branch +└── Linear history (optional) +``` + +### Definition of Done for PRs + +- [ ] Code changes complete +- [ ] All tests pass +- [ ] No linting errors +- [ ] TypeScript compilation succeeds +- [ ] Build completes successfully +- [ ] At least 1 code review approval +- [ ] Documentation updated (if needed) +- [ ] Preview deployment tested + +### Semantic Versioning + +This project uses [Semantic Versioning](https://semver.org): + +``` +MAJOR.MINOR.PATCH +│ │ │ +│ │ └── Bug fixes +│ └─────── New features (backward compatible) +└────────────── Breaking changes +``` + +#### Version Tags + +```bash +# Patch release +git tag v1.0.1 +git tag -a v1.0.1 -m "Bug fixes" + +# Minor release +git tag v1.1.0 +git tag -a v1.1.0 -m "New features" + +# Major release +git tag v2.0.0 +git tag -a v2.0.0 -m "Breaking changes" +``` + +--- + +## 8. Troubleshooting + +### Common CI/CD Issues + +#### Issue: Build Fails with TypeScript Errors + +``` +Error: TypeScript: No inputs found +``` + +**Solution**: + +1. Check `tsconfig.json` includes correct paths +2. Verify files exist in the included paths +3. Run `npx tsc --noEmit` locally to see errors + +#### Issue: ESLint Fails on Demo Routes + +``` +Error: ESLint: Demo routes should be skipped +``` + +**Solution**: + +1. This is expected behavior per project conventions +2. Demo routes in `/src/routes/demo/` are excluded from linting +3. Set `SKIP_DEMO_LINT=true` environment variable + +#### Issue: Netlify Build Fails + +``` +Error: Could not find module "@netlify/vite-plugin-tanstack-start" +``` + +**Solution**: + +1. Ensure dependencies are installed: `npm ci` +2. Check `package.json` includes the plugin +3. Verify `netlify.toml` configuration is correct + +#### Issue: Tests Fail in CI but Pass Locally + +``` +Error: Test failed - works on local machine +``` + +**Solutions**: + +1. Clear node_modules and reinstall: `rm -rf node_modules && npm ci` +2. Check Node.js version matches CI (Node 20) +3. Look for environment-specific test configurations +4. Check for timing-related issues in tests + +#### Issue: Netlify Preview Not Updating + +``` +Error: Preview deployment shows old code +``` + +**Solutions**: + +1. Check PR status for build completion +2. Wait for Netlify to finish building +3. Clear Netlify cache (Site Settings > Build & deploy > Clear cache) +4. Push a new commit to trigger rebuild + +### Debugging Failed Builds + +#### GitHub Actions Logs + +1. Go to **GitHub > Actions** tab +2. Select the failed workflow run +3. Click on the failed job +4. Expand the failed step to see logs +5. Search for error patterns: + +```bash +# Common error patterns +grep -i "error" workflow.log +grep -i "failed" workflow.log +grep -i "cannot" workflow.log +``` + +#### Netlify Build Logs + +1. Go to **Netlify Dashboard > Deploys** +2. Select the failed deploy +3. View **Deploy log** for detailed output +4. Look for: + +``` +[build] Error: ... +[build] Failed to ... +[build] Warning: ... +``` + +### Useful Commands + +```bash +# Check TypeScript locally +npx tsc --noEmit + +# Run linting +npm run lint + +# Run tests with coverage +npm run test -- --coverage + +# Check formatting +npm run format -- --check + +# Full check (format + lint + type-check) +npm run check + +# Build locally +npm run build + +# Preview build +npm run preview +``` + +### Getting Help + +- **GitHub Actions**: Check [GitHub Actions documentation](https://docs.github.com/en/actions) +- **Netlify**: Check [Netlify documentation](https://docs.netlify.com) +- **Vitest**: Check [Vitest documentation](https://vitest.dev) +- **ESLint**: Check [ESLint documentation](https://eslint.org) +- **Prettier**: Check [Prettier documentation](https://prettier.io) + +--- + +## Quick Start Checklist + +- [ ] GitHub Actions workflow created (`.github/workflows/ci.yml`) +- [ ] Environment variables template created (`.env.example`) +- [ ] This guide reviewed (`docs/ci-cd-setup.md`) +- [ ] Husky installed and configured (optional) +- [ ] Branch protection rules enabled +- [ ] Netlify connected to GitHub repository +- [ ] Environment variables set in Netlify dashboard +- [ ] First deployment verified + +--- + +## File Reference + +| File | Purpose | +| -------------------------- | ------------------------------ | +| `.github/workflows/ci.yml` | GitHub Actions CI/CD pipeline | +| `.env.example` | Environment variables template | +| `netlify.toml` | Netlify build configuration | +| `package.json` | npm scripts and dependencies | +| `tsconfig.json` | TypeScript configuration | +| `eslint.config.js` | ESLint configuration | + +--- + +## References + +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [Netlify Documentation](https://docs.netlify.com) +- [Vitest Documentation](https://vitest.dev) +- [ESLint Documentation](https://eslint.org) +- [Prettier Documentation](https://prettier.io) +- [TanStack Start Documentation](https://tanstack.com/start) diff --git a/docs/implementation-phases.md b/docs/implementation-phases.md index 73d321e..d17e150 100644 --- a/docs/implementation-phases.md +++ b/docs/implementation-phases.md @@ -6,34 +6,34 @@ Tracking document for all implementation phases of the AI Models Explorer projec A React-based AI Models Explorer application that allows users to browse, search, and filter through 500+ AI models from various providers. The application uses TanStack Start for the framework, TanStack Table for data presentation, and TanStack Query for data fetching with 24-hour caching. -**Total Estimated Time:** 22-31 days (excluding Phase 10) +**Total Estimated Time:** 20-28 days (excluding Phase 10) --- ## Progress Tracking Table -| Phase | Status | Duration | Focus Area | Key Deliverables | Review | -| ----- | ------------ | -------- | --------------------------------- | --------------------------------------------------- | --------------------------------------------------------- | -| 1 | ✅ COMPLETED | 2-3 days | Project Setup | Dependencies, folders, existing queryClient pattern | Commit: "feat: complete Phase 1 project setup" | -| 2 | ✅ COMPLETED | 1-2 days | TypeScript Types | All 27 column types defined | Audit: `docs/reviews/audit-models-types-phase2.md` - PASS | -| 3 | ✅ COMPLETED | 2-3 days | API Integration | fetchModels server function, data transform | QA: docs/qa/phase3-api-integration.md - PASS | -| 3.5 | ✅ COMPLETED | 2-3 days | Custom Server API with Pagination | Server-side pagination, search, and filtering | QA: docs/qa/phase3-5-server-api.md - PASS | -| 4 | ✅ COMPLETED | 2-3 days | Basic Table Layout | ModelList component, 27 columns, sorting | Commit: 4fa0940, QA: PASS, Review: PASS | -| 5 | ✅ COMPLETED | 2-3 days | Pagination Controls | Pagination controls UI with server-side integration | Commit: `feat(phase5): implement PaginationControls` | -| 6 | ✅ COMPLETED | 2-3 days | Search Integration | SearchBar, globalFilter, URL sync | Commit: `feat(phase6): implement SearchBar` | -| 7 | ✅ COMPLETED | 3-4 days | Filter Integration | FilterPanel, columnFilters, URL sync | Commit: `feat(phase7): implement FilterPanel` | -| 8 | ⏳ PENDING | 2-3 days | Column Visibility | ColumnVisibilityToggle, URL sync | - | -| 9 | ⏳ PENDING | 2-3 days | Virtualization & Performance | Row virtualization, loading states | - | -| 10 | ⏳ PENDING | 3-4 days | Polishing | Responsive design, accessibility, animations | - | -| 11 | 🔮 OPTIONAL | TBD | Comparison | Comparison modal, side-by-side view | TBD | +| Phase | Status | Duration | Focus Area | Key Deliverables | Review | +| ----- | ------------ | -------- | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| 1 | ✅ COMPLETED | 2-3 days | Project Setup | Dependencies, folders, existing queryClient pattern | Commit: "feat: complete Phase 1 project setup" | +| 2 | ✅ COMPLETED | 1-2 days | TypeScript Types | All 27 column types defined | Audit: `docs/reviews/audit-models-types-phase2.md` - PASS | +| 3 | ✅ COMPLETED | 2-3 days | API Integration | fetchModels server function, data transform | QA: docs/qa/phase3-api-integration.md - PASS | +| 3.5 | ✅ COMPLETED | 2-3 days | Custom Server API with Pagination | Server-side pagination, search, and filtering | QA: docs/qa/phase3-5-server-api.md - PASS | +| 4 | ✅ COMPLETED | 2-3 days | Basic Table Layout | ModelList component, 27 columns, sorting | Commit: 4fa0940, QA: PASS, Review: PASS | +| 5 | ✅ COMPLETED | 2-3 days | Pagination Controls | Pagination controls UI with server-side integration | Commit: `feat(phase5): implement PaginationControls` | +| 6 | ✅ COMPLETED | 2-3 days | Search Integration | SearchBar, globalFilter, URL sync | Commit: `feat(phase6): implement SearchBar` | +| 7 | ✅ COMPLETED | 3.5 days | Column Visibility | ColumnVisibilityToggle with in-memory state | Branch: `feature/phase7-column-visibility` | +| 8 | ✅ COMPLETED | 1 day | Simplified Filters | 3 quick filter toggles, URL sync | Commits: e77fa15, 2fd4e3d, 6b48e3a, 5a7b4ad, 825467c; PR #2, QA: docs/qa/phase8-complete-qa.md - PASS | +| 9 | ⏳ PENDING | 2-3 days | Virtualization & Performance | Row virtualization, loading states | - | +| 10 | ⏳ PENDING | 3-4 days | Polishing | Responsive design, accessibility, animations | - | +| 11 | 🔮 OPTIONAL | TBD | Comparison | Comparison modal, side-by-side view | TBD | --- ## Total Progress -- **Phases Completed:** 7 out of 11 -- **Progress:** ~64% -- **Current Phase:** Phase 8 - Column Visibility +- **Phases Completed:** 8 out of 11 +- **Progress:** ~73% +- **Current Phase:** Phase 9 - Virtualization & Performance --- @@ -190,7 +190,7 @@ A React-based AI Models Explorer application that allows users to browse, search **Duration:** 2-3 days -**Completion Notes** +### Completion Notes - **Date Completed:** December 2025 - **Commit:** 2796e63 @@ -280,7 +280,7 @@ Server-side pagination, search, and filtering **Duration:** 2-3 days -**Completion Notes** +### Completion Notes - **Date Completed:** December 2025 - **Commit:** 4fa0940 @@ -452,114 +452,452 @@ Server-side pagination, search, and filtering --- -## Phase 7: Filter Integration +## Phase 7: Column Visibility **Status:** ✅ COMPLETED -**Duration:** 3-4 days +**Duration:** 3.5 days ### Completion Notes -- **Date Completed:** December 29, 2025 -- **Commit:** `feat(phase7): implement FilterPanel with provider and capability filters` -- **QA Report:** `docs/qa/phase7-filter-integration.md` - PASS ✅ -- **Files Created:** 5 files - - `src/types/filters.ts` - FilterState interface and defaultFilters - - `src/components/FilterPanel/ProviderFilter.tsx` - Multi-select provider filter - - `src/components/FilterPanel/CapabilityFilter.tsx` - Toggle capability filter - - `src/components/FilterPanel/FilterPanel.tsx` - Main container component - - `src/components/FilterPanel/index.ts` - Export file -- **Files Modified:** 4 files - - `src/routes/index.tsx` - Integrated FilterPanel with URL sync - - `src/lib/api/models.ts` - Updated modelsQueryOptions to accept filter params - - `src/types/index.ts` - Added filter types export - - `docs/qa/phase7-filter-integration.md` - QA report +- **Date Completed:** January 1, 2026 +- **Branch:** `feature/phase7-column-visibility` +- **Implementation:** Column Visibility feature with pure in-memory state +- **Key Features:** + - ColumnVisibilityToggle component (27 columns) + - "Show All" and "Reset to Default" buttons + - Pure in-memory state (no URL/localStorage) + - No SSR/hydration issues +- **Files Created:** 3 files + - `src/types/column-visibility.ts` + - `src/components/ColumnVisibilityToggle/ColumnVisibilityToggle.tsx` + - `src/components/ColumnVisibilityToggle/index.ts` +- **Files Modified:** 2 files + - `src/routes/index.tsx` - Integrated component + - `src/types/index.ts` - Added exports + +### Objectives + +- Implement ColumnVisibilityToggle component +- Show/hide columns UI +- Use pure in-memory state (no URL sync, no localStorage) + +### Tasks + +1. **Column Toggle Component** + - Dropdown with all 27 columns + - Checkbox for each column + - Show all / Reset to defaults + +2. **Type Definitions** + - Create ColumnVisibilityState type + - Define ALL_COLUMNS array + - Define DEFAULT_VISIBLE_COLUMNS (6 columns by default) + +3. **Integration** + - Add columnVisibility state to TanStack Table + - Integrate with index.tsx + - No URL sync or localStorage (simplified approach) + +### Deliverables + +- Working column visibility toggle +- Pure in-memory state management +- Type-safe column definitions + +### Key Files + +- `src/components/ColumnVisibilityToggle/index.ts` +- `src/types/column-visibility.ts` + +--- + +## Phase 8: Simplified Filters + +**Status:** ✅ COMPLETED + +**Duration:** 1 day (simplified approach) + +**Branch:** `feature/phase8-simplified-filters` + +### Completion Notes + +- **Date Completed:** January 1, 2026 +- **Branch:** `feature/phase8-simplified-filters` +- **Pull Request:** PR #2 +- **Duration:** 1 day (as estimated) +- **Commits:** + 1. `e77fa15` - feat(phase8.1): add filter type definitions + 2. `2fd4e3d` - feat(phase8.2): create SimplifiedFilters component + 3. `6b48e3a` - feat(phase8.3): implement URL state management for filters + 4. `5a7b4ad` - feat(phase8.4): integrate server-side filtering + 5. `825467c` - feat(phase8.5): add comprehensive QA documentation +- **QA Report:** `docs/qa/phase8-complete-qa.md` - PASS ✅ - **Key Achievements:** - - FilterPanel with expandable/collapsible design - - ProviderFilter with multi-select, search, Select All/Clear All - - CapabilityFilter with toggles for reasoning, toolCall, structuredOutput - - URL state synchronization for all filter parameters + - 3 quick filter toggles (Reasoning, Tool Calling, Open Weights) + - URL synchronization (`?reasoning=true&toolCall=true&openWeights=true`) - Server-side filtering via Phase 3.5 API - - Active filter count display - - "Clear All Filters" button - - Integration with search and pagination - - Proper SSR with Route.useSearch() + - Shareable filter URLs + - Full accessibility support (WCAG 2.1 AA) + - All 27 QA tests passed +- **Files Created:** 6 files + - `src/types/filters.ts` - Filter type definitions + - `src/components/SimplifiedFilters/SimplifiedFilters.tsx` - Filter UI component + - `src/components/SimplifiedFilters/index.ts` - Component exports + - `docs/qa/phase8-1-and-8-2-qa.md` - Sub-phase QA report + - `docs/qa/phase8-3-url-state-qa.md` - URL state QA report + - `docs/qa/phase8-complete-qa.md` - Final comprehensive QA report +- **Files Modified:** 2 files + - `src/types/index.ts` - Added filter exports + - `src/routes/index.tsx` - Integrated filters with URL state, query, and table +- **Code Quality:** Zero lint errors, TypeScript strict mode compliant, all tests passing + +### Rationale for Simplified Approach + +**Decision:** Implement simplified filters instead of full filter panel + +**Reasons:** + +1. **Search Limitations:** Cannot handle boolean fields (reasoning, tool_call), numeric ranges (cost, context), or precise filtering +2. **Full Filters Removed:** Original Phase 8 (full FilterPanel) was removed in commit 9934c2c for simplification +3. **MVP Priorities:** Need quick filtering for 80% of use cases with 33% of effort +4. **Data Scale:** 87+ providers and 500+ models require some filtering capability beyond search + +**Trade-offs:** + +- Full filters (3-4 days) vs Simplified filters (1 day) +- Full filters (provider multi-select, date ranges) vs Simplified (3 toggles only) +- Full filters (80-100% coverage) vs Simplified (80% coverage for common cases) + +--- + +## Phase 8 Sub-Phases Breakdown + +### Phase 8.1: Filter Type Definitions + +**Status:** ✅ COMPLETED + +**Duration:** 30 minutes + +**Estimated:** Morning, Day 1 + +### Objectives + +- Create TypeScript type definitions for simplified filters +- Define SimpleFiltersState interface +- Define available filter options + +### Tasks + +1. **Create Filter Types** + - Create `src/types/filters.ts` + - Define `SimpleFiltersState` interface + - Add default filter values + +2. **Type Exports** + - Add filter types to `src/types/index.ts` + - Ensure proper TypeScript exports + +### Deliverables + +- `src/types/filters.ts` with complete type definitions +- Type-safe filter state management + +### Key Files + +- `src/types/filters.ts` (new) +- `src/types/index.ts` (update) + +--- + +### Phase 8.2: SimplifiedFilters Component + +**Status:** ✅ COMPLETED + +**Duration:** 1.5 hours + +**Estimated:** Mid-day, Day 1 + +### Objectives + +- Create SimplifiedFilters component with 3 quick toggle filters +- Simple, lightweight UI +- Inline layout (no dropdowns/panels) + +### Tasks + +1. **Component Structure** + - Create `src/components/SimplifiedFilters/SimplifiedFilters.tsx` + - Define component props interface + - Implement 3 checkbox toggles + +2. **Filter Toggles** + - Reasoning capability toggle + - Tool calling capability toggle + - Open weights toggle + - Simple checkbox design (no multi-select, no search) + +3. **Component Export** + - Create `src/components/SimplifiedFilters/index.ts` + - Export component for easy importing + +### Deliverables + +- SimplifiedFilters component with 3 toggles +- Clean, simple UI +- Proper TypeScript types + +### Key Files + +- `src/components/SimplifiedFilters/SimplifiedFilters.tsx` (new) +- `src/components/SimplifiedFilters/index.ts` (new) + +### Expected Implementation + +```typescript +// src/components/SimplifiedFilters/SimplifiedFilters.tsx +import type { SimpleFiltersState } from '@/types/filters' + +interface SimplifiedFiltersProps { + filters: SimpleFiltersState + onChange: (filters: SimpleFiltersState) => void +} + +export function SimplifiedFilters({ + filters, + onChange, +}: SimplifiedFiltersProps) { + return ( +