StarPunk/docs/design/hotfix-validation-script.md

Hotfix Validation Script for v1.1.1-rc.2

Quick Validation Commands

Run these commands after applying the hotfix to verify it works:

1. Check Route Registration

# In Flask shell (uv run flask shell)
from starpunk import create_app
app = create_app()

# List all admin routes
for rule in app.url_map.iter_rules():
    if 'admin' in rule.endpoint:
        print(f"{rule.endpoint:30} -> {rule.rule}")

# Expected output:
# admin.dashboard               -> /admin/
# admin.metrics_dashboard       -> /admin/metrics-dashboard
# admin.metrics                 -> /admin/metrics
# admin.health_diagnostics      -> /admin/health
# (plus CRUD routes)

2. Test URL Resolution

# In Flask shell
from flask import url_for
with app.test_request_context():
    print("Notes dashboard:", url_for('admin.dashboard'))
    print("Metrics dashboard:", url_for('admin.metrics_dashboard'))

# Expected output:
# Notes dashboard: /admin/
# Metrics dashboard: /admin/metrics-dashboard

3. Simulate Production Environment (No Monitoring Module)

# Temporarily rename monitoring module if it exists
mv starpunk/monitoring.py starpunk/monitoring.py.bak 2>/dev/null

# Start the server
uv run flask run

# Test the routes
curl -I http://localhost:5000/admin/  # Should return 302 (redirect to auth)
curl -I http://localhost:5000/admin/metrics-dashboard  # Should return 302 (not 500!)

# Restore monitoring module if it existed
mv starpunk/monitoring.py.bak starpunk/monitoring.py 2>/dev/null

4. Manual Browser Testing

After logging in with IndieAuth:

1. Navigate to /admin/ - Should show notes list
2. Click "Metrics" in navigation - Should load /admin/metrics-dashboard
3. Click "Dashboard" in navigation - Should return to /admin/
4. Create a new note - Should redirect to /admin/ after creation
5. Edit a note - Should redirect to /admin/ after saving
6. Delete a note - Should redirect to /admin/ after deletion

5. Check Error Logs

# Monitor Flask logs for any errors
uv run flask run 2>&1 | grep -E "(ERROR|CRITICAL|ImportError|500)"

# Should see NO output related to route conflicts or import errors

6. Automated Test Suite

# Run the admin route tests
uv run python -m pytest tests/test_admin_routes.py -v

# All tests should pass

Production Verification

After deploying to production:

1. Health Check

curl https://starpunk.thesatelliteoflove.com/health
# Should return 200 OK

2. Admin Routes (requires auth)

# These should not return 500
curl -I https://starpunk.thesatelliteoflove.com/admin/
curl -I https://starpunk.thesatelliteoflove.com/admin/metrics-dashboard

3. Monitor Error Logs

# Check production logs for any 500 errors
tail -f /var/log/starpunk/error.log | grep "500"
# Should see no new 500 errors

4. User Verification

1. Log in to admin panel
2. Verify both dashboards accessible
3. Perform one CRUD operation to verify redirects

Rollback Commands

If issues are discovered:

# Quick rollback to previous version
git checkout v1.1.1-rc.1
systemctl restart starpunk

# Or if using containers
docker pull starpunk:v1.1.1-rc.1
docker-compose up -d

Success Indicators

✅ No 500 errors in logs ✅ Both dashboards accessible ✅ All redirects work correctly ✅ Navigation links functional ✅ No ImportError in logs ✅ Existing functionality unchanged

Report Template

After validation, report:

HOTFIX VALIDATION REPORT - v1.1.1-rc.2

Date: [DATE]
Environment: [Production/Staging]

Route Resolution:
- /admin/ : ✅ Shows notes dashboard
- /admin/metrics-dashboard : ✅ Loads without error

Functionality Tests:
- Create Note: ✅ Redirects to /admin/
- Edit Note: ✅ Redirects to /admin/
- Delete Note: ✅ Redirects to /admin/
- Navigation: ✅ All links work

Error Monitoring:
- 500 Errors: None observed
- Import Errors: None observed
- Flash Messages: Working correctly

Conclusion: Hotfix successful, ready for production