# CI/CD Quick Fix Guide

This document provides quick solutions for common CI/CD issues in this project.

## Quick Start - Running CI/CD Locally

```bash
# Install dependencies
npm install

# Run all CI checks
npm run lint          # ESLint with auto-fix
npx tsc --noEmit      # TypeScript type checking
npm run build         # Build the application

# Run E2E tests (requires dev server)
npm run test:e2e

# Build Docker image
docker build -t codeforge:local .
docker run -p 3000:80 codeforge:local
```

## Common Issues and Fixes

### 1. "Cannot find module '@github/spark'"

**Symptom**: Import errors for `@github/spark`

**Solution**: The spark package is now implemented in `packages/spark/`. Run:
```bash
npm install
```

### 2. "ESLint couldn't find an eslint.config.js file"

**Symptom**: ESLint fails with config not found

**Solution**: The project now uses ESLint v9 flat config format. File is at `eslint.config.js`.

### 3. "Property 'spark' does not exist on type 'Window'"

**Symptom**: TypeScript errors about window.spark

**Solution**: Type definitions are in `packages/spark/src/types.d.ts` and auto-imported. Run:
```bash
npx tsc --noEmit
```

Should show 0 errors.

### 4. "Unknown file extension .ts for vite plugin"

**Symptom**: Vite can't load TypeScript plugin files

**Solution**: Plugins are now .mjs files:
- `packages/spark/src/spark-vite-plugin.mjs`
- `packages/spark/src/vitePhosphorIconProxyPlugin.mjs`

### 5. Docker Build Fails at npm run build

**Symptom**: "devDependencies not found" during Docker build

**Solution**: Dockerfile now uses `npm ci` (not `npm ci --only=production`). Rebuild:
```bash
docker build -t codeforge:latest .
```

## Auto-Fix Lint Issues

The lint command now includes auto-fix by default:

```bash
npm run lint        # Runs with --fix
npm run lint:check  # Check only, no auto-fix (for CI)
```

## Package Structure

```
/
├── packages/
│   └── spark/              # @github/spark workspace package
│       ├── src/
│       │   ├── hooks/
│       │   │   └── index.ts           # useKV hook
│       │   ├── spark-runtime.ts        # Core runtime
│       │   ├── spark.ts                # Initialization module
│       │   ├── types.d.ts              # TypeScript definitions
│       │   ├── spark-vite-plugin.mjs   # Vite plugin
│       │   └── vitePhosphorIconProxyPlugin.mjs
│       ├── package.json
│       ├── tsconfig.json
│       └── README.md
├── src/                    # Application source
├── e2e/                    # Playwright E2E tests
├── eslint.config.js        # ESLint v9 flat config
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.yml      # Docker Compose setup
└── .github/workflows/      # GitHub Actions CI/CD

```

## CI/CD Workflow Commands

### GitHub Actions
```yaml
- npm ci                    # Install dependencies
- npm run lint              # Lint with auto-fix
- npx tsc --noEmit          # Type check
- npm run build             # Build application
- npm run test:e2e          # E2E tests
```

### Local Development
```bash
npm run dev                 # Start dev server
npm run preview             # Preview production build
npm run lint                # Lint with auto-fix
npm run build               # Production build
```

## Environment Variables

No environment variables required for build. All configuration is in:
- `vite.config.ts` - Build configuration
- `tsconfig.json` - TypeScript configuration
- `eslint.config.js` - Linting configuration
- `playwright.config.ts` - E2E test configuration

## Debugging Build Issues

### Enable Verbose Logging
```bash
npm run build -- --debug
```

### Check TypeScript Compilation
```bash
npx tsc --noEmit --listFiles | grep error
```

### Check Bundle Size
```bash
npm run build
ls -lh dist/assets/
```

### Test Production Build Locally
```bash
npm run build
npm run preview
# Visit http://localhost:4173
```

## Update Dependencies

```bash
# Check for outdated packages
npm outdated

# Update all to latest compatible versions
npm update

# Update package-lock.json
npm install
```

## Troubleshooting Workspace

If workspace dependencies cause issues:

```bash
# Clean install
rm -rf node_modules package-lock.json
rm -rf packages/*/node_modules
npm install

# Verify workspace is linked
ls -la node_modules/@github/
# Should show: spark -> ../../packages/spark
```

## CI/CD Platform-Specific Notes

### GitHub Actions
- Uses Node.js 20.x
- Caches node_modules automatically
- Runs on ubuntu-latest
- Docker builds push to GHCR

### GitLab CI
- Uses node:20-alpine image
- Manual cache configuration required
- Supports parallel stages
- Docker builds push to GitLab Registry

### Jenkins
- Requires Node.js 20 installation configured
- Uses NodeJS plugin
- Needs Docker plugin for builds
- Manual workspace cleanup

### CircleCI
- Uses cimg/node:20.11 executor
- Docker layer caching available (paid)
- Requires environment variables for secrets
- Workflow dependencies via `requires`

## Performance Tips

1. **Faster npm install**: Use `npm ci` instead of `npm install` in CI
2. **Cache dependencies**: All CI configs include caching
3. **Parallel jobs**: Use where available (lint + test)
4. **Skip optional deps**: Not needed for this project
5. **Docker layer caching**: Enable in CI for faster builds

## Getting Help

1. Check `CI_CD_SIMULATION_RESULTS.md` for detailed test results
2. Check `CI_CD_GUIDE.md` for platform-specific setup
3. Review workflow files in `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/config.yml`
4. Check build logs for specific error messages

## Verification Checklist

Before pushing to CI, verify locally:

- [ ] `npm install` - Completes without errors
- [ ] `npm run lint` - No errors (warnings OK)
- [ ] `npx tsc --noEmit` - 0 errors
- [ ] `npm run build` - Generates dist/ folder
- [ ] `npm run preview` - App loads at http://localhost:4173
- [ ] Git status clean (no uncommitted changes)

## Quick Reference

| Command | Purpose | Duration |
|---------|---------|----------|
| `npm install` | Install all dependencies | ~15s |
| `npm run lint` | ESLint with auto-fix | ~3s |
| `npx tsc --noEmit` | Type checking | ~5s |
| `npm run build` | Production build | ~8s |
| `npm run test:e2e` | E2E tests | ~30s |
| `docker build` | Docker image | ~2min |

---

**Last Updated**: 2026-01-17  
**Project**: CodeForge Low-Code React App Builder  
**CI/CD Status**: ✅ READY