# GLAM Frontend - Quick Command Reference

## 🚀 Getting Started

```bash
# Navigate to project
cd /Users/kempersc/apps/glam/frontend

# Install dependencies (first time only)
npm install

# Start development server
npm run dev
# → Opens http://localhost:5173
```

---

## 🧪 Testing Commands

```bash
# Run tests in watch mode (recommended during development)
npm run test

# Run tests with interactive UI
npm run test:ui
# → Opens http://localhost:51204/__vitest__/

# Run tests once (CI/CD)
npm run test:run

# Run tests with coverage report
npm run test:coverage
# → Generates HTML report in coverage/
```

---

## 🔨 Build Commands

```bash
# Type check
npx tsc --noEmit

# Build for production
npm run build
# → Output in dist/

# Preview production build
npm run preview
# → Opens http://localhost:4173

# Lint code
npm run lint

# Format code (if prettier script added)
npx prettier --write src/
```

---

## 📦 Package Management

```bash
# Install new dependency
npm install <package>

# Install dev dependency
npm install -D <package>

# Update dependencies
npm update

# Check for outdated packages
npm outdated

# Audit for security issues
npm audit
```

---

## 🔍 Debugging

```bash
# Check Node.js version
node --version

# Check npm version
npm --version

# Clear npm cache
npm cache clean --force

# Reinstall node_modules
rm -rf node_modules package-lock.json
npm install

# Check for TypeScript errors
npx tsc --noEmit
```

---

## 📊 Project Analysis

```bash
# Count lines of code
find src -name "*.ts" -o -name "*.tsx" | xargs wc -l

# Find TODO comments
rg "TODO|FIXME" src/

# List all test files
find tests -name "*.test.ts"

# Check bundle size (after build)
npm run build
ls -lh dist/assets/
```

---

## 🧹 Cleanup

```bash
# Remove build artifacts
rm -rf dist/

# Remove test coverage
rm -rf coverage/

# Remove node_modules (nuclear option)
rm -rf node_modules/

# Clean everything and reinstall
rm -rf node_modules/ dist/ coverage/
npm install
```

---

## 🔧 Development Workflow

### Starting a New Feature

```bash
# 1. Create feature branch (if using git)
git checkout -b feature/graph-visualization

# 2. Start dev server
npm run dev

# 3. Open test UI in another terminal
npm run test:ui

# 4. Create your files
touch src/components/visualizations/GraphView/ForceDirectedGraph.tsx
touch tests/unit/force-directed-graph.test.tsx

# 5. Write tests first (TDD)
# Edit tests/unit/force-directed-graph.test.tsx

# 6. Implement feature
# Edit src/components/visualizations/GraphView/ForceDirectedGraph.tsx

# 7. Verify tests pass
npm run test:run

# 8. Check types
npx tsc --noEmit

# 9. Lint
npm run lint
```

---

## 🎯 Most Used Commands (Quick Reference)

```bash
# Development
npm run dev              # Start dev server
npm run test            # Run tests (watch mode)

# Before commit
npm run test:run        # Run all tests
npx tsc --noEmit       # Check types
npm run lint           # Lint code

# Production
npm run build          # Build for production
npm run preview        # Preview build
```

---

## 🔗 Useful URLs

```bash
# Development Server
http://localhost:5173

# Vitest UI
http://localhost:51204/__vitest__/

# Preview Server  
http://localhost:4173

# Backend API (when running)
http://localhost:8000
```

---

## 📁 Important Directories

```bash
src/                    # Source code
├── components/        # React components
├── lib/              # Core libraries
├── hooks/            # Custom React hooks
├── stores/           # Zustand stores
├── types/            # TypeScript types
├── pages/            # Page components
└── styles/           # Global styles

tests/                 # Test files
├── unit/             # Unit tests
├── integration/      # Integration tests
└── e2e/              # E2E tests

docs/plan/frontend/   # Documentation
dist/                 # Build output (generated)
coverage/             # Coverage reports (generated)
node_modules/         # Dependencies (generated)
```

---

## 🆘 Troubleshooting

### Port already in use
```bash
# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

# Or use different port
npm run dev -- --port 3000
```

### Module not found
```bash
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```

### Type errors
```bash
# Check TypeScript version
npm list typescript

# Rebuild TypeScript
npx tsc --noEmit
```

### Test failures
```bash
# Clear test cache
npx vitest --run --clearCache

# Run specific test
npm run test -- tests/unit/rdf-parser.test.ts

# Debug test
npm run test:ui
# Then click on test to see details
```

### Vite issues
```bash
# Clear Vite cache
rm -rf node_modules/.vite

# Restart dev server
npm run dev
```

---

## 🎓 Learning Commands

```bash
# View package documentation
npm docs <package-name>

# View package homepage
npm home <package-name>

# View package repository
npm repo <package-name>

# List installed packages
npm list

# List outdated packages
npm outdated

# Check package info
npm info <package-name>
```

---

## 📝 Git Commands (if using version control)

```bash
# Check status
git status

# Stage changes
git add src/ tests/

# Commit
git commit -m "feat: add force-directed graph component"

# Push
git push origin feature/graph-visualization

# View log
git log --oneline --graph --all
```

---

## 🔄 Continuous Integration

```bash
# Run full CI check locally
npm run test:run && \
npx tsc --noEmit && \
npm run lint && \
npm run build

# Single line version
npm run test:run && npx tsc --noEmit && npm run lint && npm run build
```

---

## 💡 Pro Tips

```bash
# Watch mode for TypeScript
npx tsc --noEmit --watch

# Parallel test execution
npm run test -- --threads

# Test specific file pattern
npm run test -- --grep="parser"

# Update snapshots (if using snapshot tests)
npm run test -- --update

# Run tests in specific directory
npm run test -- tests/unit/

# Generate coverage for specific files
npm run test:coverage -- --include="src/lib/**"
```

---

**Quick Access**:
- **Documentation**: `/docs/plan/frontend/`
- **Session Summary**: `SESSION_SUMMARY.md`
- **Progress Dashboard**: `PROGRESS_DASHBOARD.md`
- **README**: `README.md`

**Need Help?**
- Check `README.md` for full documentation
- Review `SESSION_SUMMARY.md` for implementation details
- Read `/docs/plan/frontend/07-quick-start-guide.md` for setup

---

*Last Updated: November 22, 2024*