gitadmin
/
mvp-factory-openhands
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
mvp-factory-openhands/CLAUDE.md

11 KiB
Raw Blame History

🚀 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 ✅

📊 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:

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

/home/bam/openhands-sdk-wrapper-sh.sh

Purpose: Wraps OpenHands CLI for n8n SSH execution

2. Usage in n8n SSH Node

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:

// 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:

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)

$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

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

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

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

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

Create Workflow

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

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

Execute Workflow

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:

# 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:

cd /home/bam && docker compose -f services/services-stack/docker-compose.yml restart

View Logs:

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:

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