mvp-factory-openhands/phase3-quickstart.md

# Phase 3 Quick Start Guide

**Goal:** Transform 7-node workflow → 11-node autonomous CI/CD with retry logic
**Time:** 4-5 hours
**Workflow ID:** `j1MmXaRhDjvkRSLa`

---

## 🚀 5-MINUTE SETUP

### 1. Get Gitea Token (Required for Status Updates)

```bash
# UI Method (Easiest):
# 1. Go to https://git.oky.sh/user/settings/applications
# 2. Click "Generate Token"
# 3. Name: n8n-autonomous-build
# 4. Scopes: repo, admin:repo_hook
# 5. Copy token (format: gho_...)
```

### 2. Create Test Repository

```bash
# Via API:
curl -X POST https://git.oky.sh/api/v1/user/repos \
  -H "X-Gitea-Token: {YOUR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"autonomous-build-test","description":"Phase 3 test repo"}'

# Or via UI:
# https://git.oky.sh → + → New Repository
```

### 3. Configure Webhook

1. Go to: `https://git.oky.sh/gitadmin/autonomous-build-test/settings/hooks`
2. Add Webhook:
   - URL: `https://n8n.oky.sh/webhook/openhands-autonomous-build`
   - Trigger: Push events
   - Active: ✓

---

## 📋 IMPLEMENTATION CHECKLIST

### Phase A: Add New Nodes (90 min)

- [ ] **Node 3:** Initialize Retry Counter
  - Type: Code
  - Code: See `phase3-code-snippets.md` → "Node 3"

- [ ] **Node 7:** Decision - Build OK?
  - Type: IF
  - Condition: `$json.build_success == true`

- [ ] **Node 8:** Update Gitea Success
  - Type: HTTP
  - URL: `https://git.oky.sh/api/v1/repos/{owner}/{repo}/statuses/{sha}`
  - Token: `{YOUR_GITEA_API_TOKEN}`

- [ ] **Node 9:** Format Error for Retry
  - Type: Code
  - Code: See `phase3-code-snippets.md` → "Node 9"

- [ ] **Node 10:** Check Retry Count
  - Type: IF
  - Condition: `$json.can_retry == true`

### Phase B: Modify Existing Nodes (60 min)

- [ ] **Node 2:** Extract Repo Info
  - Add: `repo_name`, `owner`, `branch`, `commit_sha`

- [ ] **Node 4:** Execute OpenHands Build
  - Enhance command with error feedback
  - Add data preservation pattern

- [ ] **Node 6:** Check Build Results
  - Add: `build_success`, `error_details`

- [ ] **Node 11:** Final Response
  - Support both success AND failure paths

### Phase C: Test (90 min)

- [ ] Test 1: Success Path (30 min)
- [ ] Test 2: Retry with Fixable Errors (30 min)
- [ ] Test 3: Max Retries (3 attempts) (30 min)

---

## 📚 KEY RESOURCES

| File | Purpose |
|------|---------|
| `phase3-implementation-plan.md` | Complete implementation guide (11 nodes) |
| `phase3-code-snippets.md` | Ready-to-copy code for each node |
| `phase3-quickstart.md` | This file - quick start guide |
| `phase3.md` | Original Phase 3 plan |

---

## 🔧 NODES BREAKDOWN

### Current Workflow (7 nodes)
```
[1] Gitea Webhook
[2] Extract Repo Info
[3] Start OpenHands Build
[4] Wait 10s
[5] Check Build Status
[6] Format Response
[7] Send Response
```

### Target Workflow (11 nodes)
```
[1] Gitea Webhook
[2] Extract Repo Info (MODIFY)
[3] Initialize Retry Counter (NEW)
[4] Start OpenHands Build (MODIFY)
[5] Wait 10s
[6] Check Build Results (MODIFY)
[7] Decision: Build OK? (NEW)
     ├─ YES → [8] Update Gitea Success → [11] Response
     └─ NO → [9] Format Error Feedback
                  ↓
              [10] Check Retry Count
                  ├─ YES → Loop to [4]
                  └─ NO → [11] Final Response
```

---

## ⚠️ CRITICAL REMINDERS

### 1. Data Preservation Pattern
**ALWAYS use this in SSH nodes:**
```javascript
const sshOutput = $json;
const repoData = $node["Extract Repo Info"].json;

return {
  ...repoData,  // ← PRESERVE INPUT DATA
  code: sshOutput.code,
  stdout: sshOutput.stdout,
  stderr: sshOutput.stderr
};
```

### 2. Retry Counter Initialization
**MUST initialize in Node 3:**
```javascript
$workflow.staticData = $workflow.staticData || {};
$workflow.staticData.retry_count = ($workflow.staticData.retry_count || 0) + 1;
```

### 3. SSH Node Configuration
```
Host: localhost
User: bam
Private Key: /home/bam/.ssh/n8n_key
Timeout: 300000 (5 minutes)
```

---

## 🧪 QUICK TESTS

### Test 1: Manual Workflow Trigger

```bash
curl -X POST https://n8n.oky.sh/webhook/openhands-autonomous-build \
  -H "Content-Type: application/json" \
  -d '{
    "repository": {
      "name": "test-project",
      "full_name": "gitadmin/test-project",
      "owner": {"name": "gitadmin", "username": "gitadmin"}
    },
    "ref": "refs/heads/main",
    "after": "abc123def456789012345678901234567890abcd"
  }'
```

### Test 2: SSH Connectivity

```bash
ssh -i /home/bam/.ssh/n8n_key bam@localhost \
  "sh /home/bam/openhands-sdk-wrapper-sh.sh 'Test connection'"
```

---

## 📊 SUCCESS CRITERIA

✅ **End-to-end completes:** Push → Build → Response
✅ **Retry works:** Max 3 attempts, then stop
✅ **Gitea status:** Updates to success/failure
✅ **Error feedback:** OpenHands receives previous errors
✅ **Real projects:** Works with actual MVP project

---

## 🆘 TROUBLESHOOTING

| Problem | Quick Fix |
|---------|-----------|
| Retry count always 0 | Initialize `$workflow.staticData` |
| Gitea status not updating | Check token has "repo" scope |
| Workflow hangs | Increase SSH timeout to 5 min |
| Data lost in loop | Use `$node["Node Name"].json` pattern |
| Same errors on retry | Include error in task string |

---

## 📞 CURRENT STATUS

- ✅ Phase 2 Complete
- ✅ Workflow ID: `j1MmXaRhDjvkRSLa`
- ✅ OpenHands SDK: Working
- ✅ n8n + Gitea: Configured
- ⏳ Phase 3: Ready to implement

---

## 🎯 NEXT STEPS

1. **Now:** Read `phase3-implementation-plan.md`
2. **Then:** Generate Gitea token
3. **Then:** Start with Node 3 (Initialize Retry Counter)
4. **Follow:** `phase3-code-snippets.md` for exact code

**Total Time:** 4-5 hours
**Can start immediately! 🚀**

---

*Quick Start Guide - Last Updated: 2025-12-02*