AUTOMATION SETUP GUIDE

Documentation for Developers

🤖 Automation Setup Guide

Preventing Performance Issues Automatically

Date: October 20, 2025
Status: ✅ PRODUCTION READY
Purpose: Set up automated prevention of monorepo performance issues

🎯 Overview

This guide helps you set up automatic prevention of performance issues in the monorepo. Once configured, the system will:

✅ Check health automatically on Cursor startup
✅ Monitor system health every 30 minutes
✅ Prevent commits when system is unhealthy
✅ Clean up processes automatically
✅ Alert you when thresholds are exceeded
✅ Run performance tests in CI/CD

🚀 Quick Setup (5 Minutes)

One Command Setup:

yarn setup:automation

This will:

Install git hooks (Husky)
Set up monitoring daemon (macOS)
Configure automatic health checks

Verify Setup:

# Check if git hooks are installed
ls -la .husky/pre-commit

# Check if monitoring daemon is running
launchctl list | grep monorepo

# Test health check
yarn crash:check

📋 Manual Setup (Step by Step)

Step 1: Install Git Hooks

# Install Husky (if not already installed)
npm install --save-dev husky
npx husky install

# The pre-commit hook is already created at:
# .husky/pre-commit

What it does:

Runs health check before every commit
Prevents commits when system is unhealthy
Automatically fixes minor issues

Test it:

git add .
git commit -m "test"
# You should see health check running

Step 2: Set Up Monitoring Daemon (macOS)

# Run the setup script
yarn setup:monitoring

# Or manually:
bash tools/scripts/setup-monitoring-daemon.sh

What it does:

Checks monorepo health every 30 minutes
Runs automatically on system startup
Logs results to ~/Library/Logs/monorepo-health.log

Verify it's running:

# Check if daemon is loaded
launchctl list | grep monorepo

# View logs
tail -f ~/Library/Logs/monorepo-health.log

Management commands:

# Start daemon
launchctl load ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

# Stop daemon
launchctl unload ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

# Restart daemon
launchctl unload ~/Library/LaunchAgents/com.monorepo.healthcheck.plist
launchctl load ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

Step 3: Configure Cursor/VS Code

The setup has already created:

.vscode/tasks.json - Automatic tasks
.vscode/settings.json - Performance optimizations

Automatic tasks include:

Health check on folder open
Continuous monitoring option
Performance monitoring during builds

Manual trigger:

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows)
Type "Run Task"
Select "Monorepo Health Check on Startup"

Step 4: Set Up CI/CD (GitHub Actions)

The workflow file is already created at: .github/workflows/performance-check.yml

It will:

✅ Run on every pull request
✅ Check TypeScript configurations
✅ Verify NX configuration
✅ Test build performance
✅ Monitor process counts
✅ Comment warnings on PRs

No action needed - it will run automatically on your next PR.

🔧 Configuration

Monitoring Frequency

Edit the daemon to change frequency:

# Edit the plist file
nano ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

# Change this value (in seconds):
<key>StartInterval</key>
<integer>1800</integer>  <!-- 30 minutes = 1800 seconds -->

# Reload daemon after changes
launchctl unload ~/Library/LaunchAgents/com.monorepo.healthcheck.plist
launchctl load ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

Recommended frequencies:

Development: 1800 seconds (30 minutes)
Heavy builds: 900 seconds (15 minutes)
Light work: 3600 seconds (60 minutes)

Health Check Thresholds

Edit tools/scripts/monorepo-health-check.js:

// Current thresholds:
const health = {
  maxNodeProcesses: 10,        // Increase if needed
  maxCursorProcesses: 5,       // Increase if needed
  maxTsserverProcesses: 4,     // Increase if needed
  maxMemoryMB: 8 * 1024        // 8GB, increase for more memory
};

Git Hook Behavior

Edit .husky/pre-commit to change behavior:

# Current behavior: Fails commit if unhealthy
# Change to: Warn but allow commit
if [ $? -ne 0 ]; then
  echo "⚠️  Warning: System health check failed"
  echo "    Proceeding with commit anyway..."
  # Remove 'exit 1' to allow commit
fi

📊 Monitoring & Logs

View Monitoring Logs:

# Real-time monitoring
tail -f ~/Library/Logs/monorepo-health.log

# Error logs
tail -f ~/Library/Logs/monorepo-health-error.log

# Last 50 entries
tail -50 ~/Library/Logs/monorepo-health.log

Health Check History:

# View historical health scores
grep "HEALTH SCORE" ~/Library/Logs/monorepo-health.log

# View critical issues
grep "CRITICAL" ~/Library/Logs/monorepo-health.log

# View automatic fixes
grep "Cleanup" ~/Library/Logs/monorepo-health.log

🎯 Daily Workflow

With Automation Enabled:

Morning:
  1. Open Cursor
     → Automatic health check runs ✅
  
  2. Start working
     → Monitoring daemon checks every 30 min ✅
  
  3. Commit changes
     → Pre-commit hook checks health ✅
  
  4. Push to GitHub
     → CI/CD checks performance ✅

If issues detected:
  → Automatic cleanup runs ✅
  → Desktop notification (optional) 📱
  → Logs to file for review 📝

Manual Checks (Optional):

# Quick health check anytime
yarn crash:check

# Full performance report
yarn perf:report

# Force cleanup if needed
yarn crash:fix

🚨 Troubleshooting Automation

Git Hooks Not Running?

# Reinstall hooks
npx husky install

# Verify hook is executable
chmod +x .husky/pre-commit

# Test hook manually
.husky/pre-commit

Monitoring Daemon Not Working?

# Check if it's loaded
launchctl list | grep monorepo

# Check logs for errors
tail -20 ~/Library/Logs/monorepo-health-error.log

# Reload daemon
bash tools/scripts/setup-monitoring-daemon.sh

Cursor Tasks Not Running?

# Verify tasks file exists
cat .vscode/tasks.json

# Manually run task:
# Cmd+Shift+P → "Tasks: Run Task" → Select task

CI/CD Failing?

# Check workflow file
cat .github/workflows/performance-check.yml

# Test locally
yarn build:gograb:fast
node tools/scripts/performance-audit.js

🎉 Verification Checklist

After setup, verify everything is working:

Git Hooks

git add .
git commit -m "test" --dry-run
# Should show health check running

Monitoring Daemon

launchctl list | grep monorepo
# Should show daemon loaded

Cursor Tasks

# Open Cursor → Check terminal for health check
# Should run automatically on folder open

CI/CD

# Create a test PR
# Check Actions tab for performance check

Manual Commands

yarn crash:check   # Should work
yarn crash:fix     # Should work
yarn perf:report   # Should work

📈 Expected Results

Before Automation:

❌ Manual monitoring required
❌ Issues discovered too late
❌ Reactive problem solving
❌ Inconsistent maintenance
❌ Developers forget to check

After Automation:

✅ Continuous automatic monitoring
✅ Issues caught early
✅ Proactive prevention
✅ Consistent maintenance
✅ Zero effort from developers

🔄 Disabling Automation

Temporarily Disable:

# Disable git hooks
mv .husky/pre-commit .husky/pre-commit.disabled

# Disable monitoring daemon
launchctl unload ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

# Disable Cursor tasks
mv .vscode/tasks.json .vscode/tasks.json.disabled

Permanently Remove:

# Remove git hooks
rm -rf .husky

# Remove monitoring daemon
launchctl unload ~/Library/LaunchAgents/com.monorepo.healthcheck.plist
rm ~/Library/LaunchAgents/com.monorepo.healthcheck.plist

# Remove Cursor config
rm .vscode/tasks.json .vscode/settings.json

💡 Pro Tips

1. Custom Notifications (macOS)

Add to monorepo-health-check.js:

# Install node-notifier
yarn add -D node-notifier

# Add to script:
const notifier = require('node-notifier');
if (healthScore < 60) {
  notifier.notify({
    title: '⚠️ Monorepo Health Alert',
    message: `Health score: ${healthScore}%`,
    sound: true
  });
}

2. Slack Notifications

Add webhook to monitoring:

const axios = require('axios');
if (healthScore < 60) {
  axios.post(process.env.SLACK_WEBHOOK, {
    text: `Monorepo health critical: ${healthScore}%`
  });
}

3. Weekly Reports

Schedule weekly email reports:

# Add to crontab
0 9 * * MON cd /path/to/editor && yarn perf:report | mail -s "Weekly Performance Report" [email protected]

📚 Related Documentation

✅ Success Criteria

You'll know automation is working when:

✅ Health checks run without manual intervention
✅ You receive alerts before issues become critical
✅ Git commits are blocked when system is unhealthy
✅ Performance regressions are caught in CI/CD
✅ You never experience resource exhaustion again

Your monorepo is now self-monitoring and self-healing! 🚀

Last Updated: October 20, 2025
Setup Time: 5 minutes
Maintenance: Zero (fully automated)