mvp-factory-openhands/CLAUDE.md

# 🚀 AI Dev Factory - Session Continuation Guide

**Last Updated:** 2025-12-02
**Current Phase:** Phase 2 - OpenHands Integration (SDK Mode) ✅ COMPLETED
**Current Approach:** OpenHands SDK via SSH wrapper ✅

---

# Summary Instructions
When you are using compact, please focus on test output and code changes

---

---

## 📊 CURRENT STATUS

### ✅ What's Working:
- **Gitea:** https://git.oky.sh (HTTPS, PostgreSQL backend)
- **n8n:** https://n8n.oky.sh (HTTPS, workflow automation)
- **Caddy:** Auto SSL with Let's Encrypt
- **SSH:** n8n → localhost credentials configured and working
- **OpenHands CLI:** `/home/bam/.local/bin/openhands` (v1.3.0)
- **OpenHands SDK Wrapper:** `/home/bam/openhands-sdk-wrapper-sh.sh` (sh-compatible)
- **Working n8n Workflow:** "Gitea → OpenHands - FIXED WITH PASSTHROUGH" (ID: j1MmXaRhDjvkRSLa)
- **Data Preservation:** Fixed using `$node["Node Name"].json` pattern

### ✅ Completed (Phase 2):
- SSH Authentication Fixed
- n8n Workflow Created & tested
- Build/test cycle functional
- Data loss issue resolved
- Repository cleanup (7 files removed)
- Testing infrastructure created

### 🎯 Phase 2 Goal (COMPLETED):
The CI/CD pipeline is fully operational: Gitea push → n8n → OpenHands SDK (via SSH) → Build/Test → Response

---

## 🔧 SYSTEM CONFIGURATION

### VM Details:
```
Hostname: ai-dev-node
IP: 10.10.10.11
User: bam
CPU: 8 vCPU
RAM: 24GB
OS: Ubuntu 22.04
```

### Services Running:
```bash
cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps
# Services: caddy, gitea, n8n, postgres
```

### API Keys & Credentials:
```
# OpenHands API Keys:
/home/bam/openhands/.env
Contains: MINIMAX_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY

# n8n API Key (JWT Token):
/home/bam/.n8n_api_key
Used for: Creating, activating, editing workflows via API

# SSH Key for n8n:
/home/bam/.ssh/n8n_key
Used for: SSH authentication from n8n to localhost
```

### 📚 Documentation References:
- **Phase 2 Details:** `phase2.md`
- **Phase 3 Plan:** `phase3.md`
- **n8n API Reference:** `n8n-api.md`
- **Data Preservation Solution:** `N8N_DATA_PRESERVATION_SOLUTION.md`
- **Gitea Webhook Setup:** `GITEA_N8N_WEBHOOK_GUIDE.md`
- **Test Scripts:** `test-scripts/README.md`

---

## 🚀 OPENHANDS SDK APPROACH

### Overview
Use **OpenHands CLI directly via SSH** in n8n workflows instead of running a server API.

### Why SDK Approach?
- ✅ **Reliable** - No Docker container issues or port conflicts
- ✅ **Simple** - Direct CLI execution without API complexity
- ✅ **Shell-compatible** - Works in SSH environment without Python dependencies
- ✅ **Proven** - Successfully tested with n8n workflows

### Key Components:

#### 1. SDK Wrapper Script
```bash
/home/bam/openhands-sdk-wrapper-sh.sh
```
**Purpose:** Wraps OpenHands CLI for n8n SSH execution

#### 2. Usage in n8n SSH Node
```javascript
Command: sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task here"
Authentication: privateKey
Options:
  passThrough: true
```

#### 3. Critical Pattern: Data Preservation
SSH nodes overwrite ALL data. Use `$node` to access previous node output:

```javascript
// In node after SSH
const sshOutput = $json;
const repoData = $node["Extract Repo Info"].json;

return {
  ...repoData,              // ← Repository data preserved!
  code: sshOutput.code,
  signal: sshOutput.signal,
  stdout: sshOutput.stdout,
  stderr: sshOutput.stderr,
  status: 'SUCCESS'
};
```

**See:** `N8N_DATA_PRESERVATION_SOLUTION.md` for complete solution

#### 4. Testing Scripts
See `/home/bam/claude/mvp-factory/test-scripts/README.md` for testing instructions

---

## 🎯 WORKING N8N WORKFLOW

### Current Production Workflow
**Name:** "Gitea → OpenHands - FIXED WITH PASSTHROUGH"
**ID:** `j1MmXaRhDjvkRSLa`
**Status:** ✅ Active
**Webhook:** `https://n8n.oky.sh/webhook/openhands-fixed-test`

### Workflow Structure:
```
[1] Gitea Webhook (POST)
     ↓
[2] Extract Repo Info (Code node)
     ↓
[3] Start OpenHands Build (SSH node)
     → sh /home/bam/openhands-sdk-wrapper-sh.sh "<task>"
     ↓
[4] Wait 10s for Initialization
     ↓
[5] Check Build Status (Code node)
     → Uses $node["Extract Repo Info"].json to preserve data
     ↓
[6] Format Build Response (Code node)
     ↓
[7] Send Response (HTTP Response node)
```

### Quick Test:
```bash
curl -X POST https://n8n.oky.sh/webhook/openhands-fixed-test \
  -H "Content-Type: application/json" \
  -d '{
    "repository": {
      "name": "test-project",
      "full_name": "gitadmin/test-project"
    },
    "ref": "refs/heads/main",
    "after": "abc123def456"
  }'
```

---

## 🎯 PHASE 3: AUTONOMOUS BUILD TEST MVP

### Overview
Build production-ready autonomous CI/CD workflow with retry logic, error feedback, and commit status updates.

### 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)**
```javascript
$workflow.staticData = $workflow.staticData || {};
$workflow.staticData.retry_count = ($workflow.staticData.retry_count || 0) + 1;

if ($workflow.staticData.retry_count >= 3) {
  return { action: 'fail', message: 'Max retries exceeded' };
}
```

**B. Error Collection & Formatting**
```javascript
const errors = sshOutput.stderr || sshOutput.stdout;
const errorMsg = `Build failed. Errors:\n${errors}\n\nPlease fix these issues.`;

return {
  status: 'FAILED',
  error_message: errorMsg,
  retry_count: $workflow.staticData.retry_count
};
```

**C. Feedback Loop**
```javascript
const task = `Build project /workspace/${project_name}.
Previous build failed with errors: ${previous_error}
Please fix these issues and ensure a successful build.`;
```

**D. Gitea Commit Status Update**
```bash
POST https://git.oky.sh/api/v1/repos/{owner}/{repo}/statuses/{sha}
Authorization: token {GITEA_TOKEN}
Body:
{
  "state": "success",
  "description": "Build passed",
  "context": "openhands/autonomous-build"
}
```

### Success Criteria:
- [ ] End-to-end workflow completes successfully
- [ ] OpenHands executes build tasks autonomously
- [ ] Retry logic works (max 3 attempts)
- [ ] Error feedback to OpenHands
- [ ] Gitea commit status updated
- [ ] Tested with real MVP project build

### Implementation Steps:
1. Create test repository in Gitea
2. Configure Gitea webhook
3. Build n8n workflow with retry logic
4. Test successful build path
5. Test failure path with retry
6. Test max retries path
7. Test Gitea commit status updates
8. Test with real MVP project

**See:** `phase3.md` for complete detailed plan

---

## 🔑 N8N API QUICK REFERENCE

See `n8n-api.md` for complete documentation

### Common Operations:

#### List Workflows
```bash
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows
```

#### Create Workflow
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  -H "Content-Type: application/json" \
  https://n8n.oky.sh/api/v1/workflows \
  -d '{"name":"My Workflow","nodes":[...]}'
```

#### Activate Workflow
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/activate
```

#### Execute Workflow
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/execute
```

---

## 📚 REFERENCE COMMANDS

### Quick Status Check:
```bash
# All services status
cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps

# n8n workflows via API
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows
```

### Restart Services:
```bash
cd /home/bam && docker compose -f services/services-stack/docker-compose.yml restart
```

### View Logs:
```bash
docker logs -f n8n
docker logs -f caddy
docker logs -f gitea
```

### Testing SDK:
See `/home/bam/claude/mvp-factory/test-scripts/README.md`

---

## 🔐 CREDENTIALS REFERENCE

### Login Credentials:
- **n8n URL:** https://n8n.oky.sh (User: admin)
- **Gitea URL:** https://git.oky.sh (Admin account)

### API Keys & Tokens:
- **OpenHands (MiniMax):** `/home/bam/openhands/.env` → MINIMAX_API_KEY
- **OpenHands (DeepSeek):** `/home/bam/openhands/.env` → DEEPSEEK_API_KEY
- **n8n API Token:** `/home/bam/.n8n_api_key` (JWT format)
- **SSH Private Key:** `/home/bam/.ssh/n8n_key`
- **Gitea API Token:** Generated in Gitea user settings

---

## 📝 KEY LEARNINGS

### OpenHands SDK vs API Server
- **SDK via SSH:** ✅ Reliable, simple, production-ready
- **API Server:** ❌ Docker complexity, port conflicts, reliability issues

### n8n Data Flow
- SSH nodes **overwrite ALL data** - Use `$node["Previous Node"].json`
- `passThrough: true` does NOT preserve input data
- Code nodes can preserve data by merging with previous output

### Best Practices
- Use `$node` pattern for data preservation after nodes that overwrite
- Test SDK scripts before integrating into n8n
- Keep API keys in secure locations with proper permissions (600)
- Implement retry logic with max attempts to prevent infinite loops
- Update commit status in Gitea for better visibility

---

## 🏆 PROJECT COMPLETION STATUS

**✅ PHASES COMPLETE:**

1. **Phase 1: Infrastructure Setup** ✅
   - Gitea, n8n, Caddy running with SSL
   - Docker compose configured
   - SSH authentication working

2. **Phase 2: OpenHands Integration (SDK)** ✅
   - SDK wrapper created and tested
   - n8n workflow integrated
   - Build/test cycle functional
   - Data preservation fixed
   - Repository cleaned up
   - Documentation complete
   - **Details:** See `phase2.md`

**🎯 PHASE 3: AUTONOMOUS BUILD TEST MVP** (In Progress)

**Phase 3 Complete When:**
- [ ] Retry logic working (max 3 attempts)
- [ ] Error feedback to OpenHands
- [ ] Commit status updates in Gitea
- [ ] Tested with real MVP project build
- **Plan:** See `phase3.md`

---

## 🎉 FINAL STATUS

**Repository:** https://git.oky.sh/gitadmin/mvp-factory-openhands
**n8n Instance:** https://n8n.oky.sh
**Production Workflow:** Active & Tested (ID: j1MmXaRhDjvkRSLa)
**Data Preservation:** Working
**Documentation:** Organized & Updated
**Phase 2:** ✅ COMPLETE
**Phase 3:** 🚀 IN PROGRESS

**Current Status:** Building Phase 3 - Autonomous Build Test MVP

---

*Last Updated: 2025-12-02*
*Phase 2 complete, Phase 3 in progress*