mvp-factory-openhands/phase3.md

# Phase 3: Autonomous Build Test MVP - Detailed Plan

**Status:** 🚀 IN PROGRESS
**Estimated Duration:** 4-5 hours
**Goal:** Build production-ready autonomous CI/CD workflow with retry logic

## ⏱️ Time Estimation

| Step | Activity | Estimated Time | Notes |
|------|----------|----------------|-------|
| 1 | Setup Test Repository | 20 min | Create repo, add sample Node.js project |
| 2 | Configure Gitea Webhook | 15 min | Set up webhook in Gitea |
| 3 | Build n8n Workflow (Base) | 60 min | Create 11-node workflow structure |
| 4 | Implement Retry Logic | 45 min | Add staticData counter, decision nodes |
| 5 | Test Success Path | 30 min | Verify workflow completes on valid code |
| 6 | Test Failure Path | 45 min | Test with intentional errors |
| 7 | Test Retry Loop | 45 min | Verify multiple retries work |
| 8 | Test Max Retries | 30 min | Ensure stops after 3 attempts |
| 9 | Gitea Status Updates | 30 min | Implement commit status API calls |
| 10 | Real Project Test | 45 min | Test with actual MVP project |
| 11 | Documentation | 30 min | Document workflow configuration |
| **Total Estimated** | **4-5 hours** | | Can be split across 2-3 sessions |

## 📅 Timeline Projection

**Starting:** 2025-12-02
**Expected Completion:** 2025-12-02 (same day, 4-5 hours total)

**Session 1 (2 hours):** Steps 1-5 (Setup + Base workflow + Success test)
**Session 2 (2 hours):** Steps 6-9 (Failure tests + Gitea integration)
**Session 3 (1 hour):** Steps 10-11 (Real project test + documentation)

---

## Overview

Phase 3 leverages Phase 2 learnings to create an autonomous build/test system that can:
- Execute builds automatically
- Detect failures
- Provide feedback to OpenHands
- Retry with improved instructions
- Update commit status in Gitea
- Prevent infinite loops with max retry limit

## Workflow: "Autonomous Build Test"

### Flow Design

```
[1] Git Push (Gitea webhook)
     ↓
[2] Extract commit info (Code node)
     ↓
[3] Start OpenHands (SSH node)
     → Task: "Build project in /workspace/[project]"
     ↓
[4] Wait for completion (Wait node)
     ↓
[5] Check build results (Code node)
     → Capture exit code + errors
     ↓
[6] Decision: Build OK?
     ├─ YES → [7] Update Gitea status → [8] Success notification
     └─ NO → [9] Format error feedback
               ↓
          [10] Retry counter check
               ├─ < 3 → Back to [3] (retry with feedback)
               └─ ≥ 3 → [11] Final failure notification
```

## Key Components

### A. Iteration Counter (n8n staticData)

**Purpose:** Track retry attempts to prevent infinite loops

**Implementation in Code Node:**
```javascript
// Initialize retry counter
$workflow.staticData = $workflow.staticData || {};
$workflow.staticData.retry_count = ($workflow.staticData.retry_count || 0) + 1;

// Get current retry count
const retryCount = $workflow.staticData.retry_count;

// Check max retries
if (retryCount >= 3) {
  return {
    action: 'fail',
    message: 'Max retries (3) exceeded',
    retry_count: retryCount,
    status: 'FAILED'
  };
}

return {
  action: 'retry',
  retry_count: retryCount,
  status: 'IN_PROGRESS'
};
```

### B. Error Collection & Formatting

**Purpose:** Extract meaningful errors from OpenHands output for feedback

**Implementation:**
```javascript
// Collect errors from OpenHands output
const sshOutput = $json;
const errors = sshOutput.stderr || sshOutput.stdout || 'Unknown error';

// Parse and format error message
const errorMsg = `Build failed with the following errors:
${errors}

Please analyze these errors and fix the issues to ensure a successful build.
Focus on:
1. Dependency issues (npm install errors)
2. Build script failures
3. Code syntax errors
4. Configuration problems

After fixing, the project should build successfully with: npm install && npm run build`;

// Include previous errors in feedback
return {
  status: 'FAILED',
  error_message: errorMsg,
  stdout: sshOutput.stdout,
  stderr: sshOutput.stderr,
  code: sshOutput.code,
  retry_count: $workflow.staticData.retry_count
};
```

### C. Feedback Loop Mechanism

**Purpose:** Improve retry attempts by providing specific error feedback to OpenHands

**Implementation:**
```javascript
// Get previous error
const previousError = $json.error_message || 'Unknown error';

// Build enhanced task with feedback
const projectName = $node["Extract Repo Info"].json.repo_name;
const task = `Build and test the project at /workspace/${projectName}.

PREVIOUS BUILD FAILED with errors:
${previousError}

Please:
1. Analyze the error messages carefully
2. Fix all identified issues
3. Ensure npm install completes successfully
4. Ensure npm run build completes successfully
5. Report any remaining issues clearly

This is retry attempt #${$workflow.staticData.retry_count}. Please be thorough and fix all problems.`;
```

### D. Gitea Commit Status Update

**Purpose:** Update commit status in Gitea for visibility

**HTTP Node Configuration:**
```bash
# URL
POST https://git.oky.sh/api/v1/repos/{owner}/{repo}/statuses/{sha}

# Headers
Authorization: token {GITEA_API_TOKEN}
Content-Type: application/json

# Body (Success)
{
  "state": "success",
  "description": "Build passed ✅",
  "context": "openhands/autonomous-build",
  "target_url": "https://n8n.oky.sh"
}

# Body (Failure)
{
  "state": "failure",
  "description": "Build failed after 3 attempts ❌",
  "context": "openhands/autonomous-build",
  "target_url": "https://n8n.oky.sh"
}
```

**Getting Gitea Token:**
1. Go to Gitea → Settings → Applications
2. Generate Access Token
3. Use token in HTTP node

### E. Success Notification

**Purpose:** Notify when build succeeds

**Options:**
- HTTP to Slack/Discord
- Email notification
- Gitea commit status update only

**Implementation:**
```javascript
// Format success message
const successMsg = {
  status: 'SUCCESS',
  repo: $node["Extract Repo Info"].json.repo_name,
  branch: $node["Extract Repo Info"].json.branch,
  commit: $node["Extract Repo Info"].json.commit_sha.substring(0, 8),
  message: 'Build completed successfully',
  retry_count: $workflow.staticData.retry_count,
  emoji: '✅'
};

return successMsg;
```

## Test Sequence

### 1. Create Test Repository
```bash
# In Gitea UI or via API
curl -X POST https://git.oky.sh/api/v1/user/repos \
  -H "Authorization: token {GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"autonomous-build-test","description":"Test repo for Phase 3"}'
```

### 2. Configure Webhook
- **URL:** `https://n8n.oky.sh/webhook/autonomous-build-test`
- **Trigger:** Push events
- **Active:** Yes

### 3. Build n8n Workflow

**Nodes Required:**
1. **Webhook** - Receive Gitea push
2. **Extract Repo Info** - Parse commit data
3. **Initialize Retry** - Set retry counter
4. **OpenHands Build** - Execute build via SSH
5. **Wait** - Wait for completion
6. **Check Results** - Evaluate build success
7. **Decision** - Split success/failure paths
8. **Update Gitea Status** - Success path
9. **Format Error** - Failure path
10. **Check Retry Count** - Decision node
11. **Retry Loop** - Back to OpenHands or final failure

### 4. Test Successful Build

**Steps:**
1. Push code with no errors to test repo
2. Webhook triggers workflow
3. OpenHands builds successfully
4. Gitea status updated to "success"
5. Success notification sent

**Expected Result:**
```json
{
  "status": "SUCCESS",
  "repo": "autonomous-build-test",
  "branch": "main",
  "commit": "abc123de",
  "message": "Build completed successfully",
  "emoji": "✅"
}
```

### 5. Test Failure Path with Retry

**Steps:**
1. Push code with intentional errors
2. Webhook triggers workflow
3. OpenHands fails build
4. Errors formatted and sent back
5. Retry counter increments
6. OpenHands tries again with feedback
7. Either succeeds or fails again

**Expected Result (1st failure):**
```json
{
  "status": "FAILED",
  "error_message": "Build failed with errors:...",
  "retry_count": 1
}
```

**Expected Result (2nd attempt):**
- OpenHands receives: "Previous build failed with: [errors]"
- Improved task with specific feedback
- Either succeeds or fails again

### 6. Test Max Retries

**Steps:**
1. Push code with persistent errors
2. Let workflow retry 3 times
3. After 3rd failure, stop retrying
4. Send final failure notification
5. Update Gitea status to "failure"

**Expected Result (3rd failure):**
```json
{
  "status": "FAILED",
  "message": "Max retries (3) exceeded",
  "retry_count": 3
}
```

## Implementation Steps

### Step 1: Setup Test Repository
- [ ] Create test repository in Gitea
- [ ] Add a simple Node.js project with build script
- [ ] Configure Gitea webhook

### Step 2: Create n8n Workflow
- [ ] Import or create new workflow
- [ ] Configure all 11 nodes
- [ ] Test with manual trigger

### Step 3: Configure Credentials
- [ ] SSH credentials for n8n
- [ ] Gitea API token for status updates
- [ ] Notification endpoints (Slack/Email)

### Step 4: Test Success Path
- [ ] Push valid code
- [ ] Verify workflow completes
- [ ] Check Gitea status updated
- [ ] Verify notification sent

### Step 5: Test Retry Logic
- [ ] Push code with errors
- [ ] Verify failure detected
- [ ] Verify retry occurs
- [ ] Verify feedback provided
- [ ] Test multiple retries

### Step 6: Test Max Retries
- [ ] Push persistent errors
- [ ] Verify 3 attempts made
- [ ] Verify stops after 3rd attempt
- [ ] Verify final failure notification

### Step 7: Test with Real Project
- [ ] Use actual MVP project
- [ ] Verify build process works
- [ ] Test error scenarios
- [ ] Document results

### Step 8: Document & Deploy
- [ ] Document workflow configuration
- [ ] Create user guide
- [ ] Deploy to production
- [ ] Monitor initial runs

## Success Criteria

**Must Have:**
- [ ] End-to-end workflow completes successfully
- [ ] OpenHands executes build tasks autonomously
- [ ] n8n detects completion and checks results
- [ ] Feedback loop works (test at least 1 retry)
- [ ] Retry counter prevents infinite loops (max 3)
- [ ] Gitea commit status updated appropriately
- [ ] Notifications sent for success/failure

**Nice to Have:**
- [ ] Error categorization (dependency vs syntax)
- [ ] Build time tracking
- [ ] Detailed build logs stored
- [ ] Slack/Discord notifications
- [ ] Email alerts for failures

## Reference Files

**SDK Wrapper:**
- `/home/bam/claude/mvp-factory/test-scripts/openhands-sdk-wrapper-sh.sh`

**Phase 2 Learnings:**
- Data preservation pattern: `$node["Node Name"].json`
- SSH node overwrites data: `{code, stdout, stderr}`
- n8n API usage: `/home/bam/.n8n_api_key`

**n8n API Documentation:**
- See `n8n-api.md` for complete API reference

**Existing Workflow:**
- Workflow ID: `j1MmXaRhDjvkRSLa`
- See `N8N_DATA_PRESERVATION_SOLUTION.md` for details

## Troubleshooting

### Retry Counter Issues
**Symptom:** Retry count always 1
**Solution:** Initialize staticData properly: `$workflow.staticData = $workflow.staticData || {};`

### Gitea Status Not Updating
**Symptom:** Commit status stays "pending"
**Solution:** Check Gitea token has correct permissions, verify URL format

### OpenHands Not Using Feedback
**Symptom:** Subsequent retries have same errors
**Solution:** Ensure error message is included in task string for retry

### Workflow Hangs
**Symptom:** Workflow stops after OpenHands execution
**Solution:** Add Wait node, ensure timeout configured

## Phase 3 Timeline

**Estimated Duration:** 3-4 hours

**Breakdown:**
- Step 1-2: Setup (30 min)
- Step 3-4: Basic workflow (60 min)
- Step 5-6: Test retry logic (90 min)
- Step 7: Real project test (30 min)
- Step 8: Documentation (30 min)

---

*Phase 3 Planning - Last Updated: 2025-12-02*
*Ready for implementation*