9.6 KiB

Raw Blame History

🚀 AI Dev Factory - Session Continuation Guide

Last Updated: 2025-12-02 Current Phase: Phase 2 ✅ COMPLETED | Phase 3 🚀 IN PROGRESS Approach: OpenHands SDK via SSH wrapper

📋 Summary Instructions

When using compact mode, focus on test output and code changes.

Efficiency Guides:

Claude Code optimization: claude-code-subagents-doc.md
OpenHands optimization: openhands-subagents-doc.md

📊 CURRENT STATUS

✅ What's Working

Gitea: https://git.oky.sh (HTTPS, PostgreSQL)
n8n: https://n8n.oky.sh (HTTPS, workflow automation)
Caddy: Auto SSL with Let's Encrypt
SSH: n8n ↔ localhost credentials working
OpenHands CLI: /home/bam/.local/bin/openhands (v1.3.0)
SDK Wrapper: /home/bam/openhands-sdk-wrapper-sh.sh (sh-compatible)
Production Workflow: ID j1MmXaRhDjvkRSLa ✅ Active
Data Preservation: Using $node["Node Name"].json pattern

✅ Phase 2 Completed

The CI/CD pipeline is operational: Gitea push → n8n → OpenHands SDK → Build/Test → Response

🎯 Phase 3 Goal

Build autonomous CI/CD workflow with retry logic, error feedback, and commit status updates.

Plan: See phase3.md for complete 11-step implementation

🔧 SYSTEM CONFIGURATION

VM Specs

Hostname: ai-dev-node | IP: 10.10.10.11 | User: bam
CPU: 8 vCPU | RAM: 24GB | OS: Ubuntu 22.04

Services

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
n8n API Token:         /home/bam/.n8n_api_key (JWT)
SSH Private Key:       /home/bam/.ssh/n8n_key
Gitea API Token:       Generated in Gitea settings

📚 Documentation Files

phase2.md                    - Phase 2 complete documentation (~8-10 hours)
phase3.md                    - Phase 3 detailed plan (4-5 hours)
n8n-api.md                   - Complete n8n API reference
openhands-subagents-doc.md   - OpenHands sub-agents guide
claude-code-subagents-doc.md - Claude Code sub-agents guide
custom-subagents-usage-guide.md - Custom project-specific sub-agents guide
agent-templates.md           - Copy-paste ready agent templates
N8N_DATA_PRESERVATION_SOLUTION.md
GITEA_N8N_WEBHOOK_GUIDE.md
test-scripts/README.md       - 10 testing scripts with guide

🚀 OPENHANDS SDK APPROACH

Use OpenHands CLI directly via SSH in n8n workflows (not server API).

Why SDK?

✅ Reliable (no Docker/port conflicts)
✅ Simple (direct CLI execution)
✅ Shell-compatible (no Python needed)
✅ Proven (tested successfully)

SDK Wrapper

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

Usage in n8n SSH Node

Command: sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task"
Authentication: privateKey

⚠️ Critical: Data Preservation Pattern

SSH nodes overwrite ALL data. Use $node to preserve input:

const sshOutput = $json;
const repoData = $node["Extract Repo Info"].json;

return {
  ...repoData,              // ← Preserves repository data!
  code: sshOutput.code,
  stdout: sshOutput.stdout,
  stderr: sshOutput.stderr,
  status: 'SUCCESS'
};

See: N8N_DATA_PRESERVATION_SOLUTION.md for complete solution

🤖 CUSTOM SUB-AGENTS

Create project-specific sub-agents with specialized knowledge:

Available Custom Agents:

n8n Workflow Specialist - Workflow design, debugging, data preservation
OpenHands SDK Specialist - CLI integration, task optimization
Gitea Integration Specialist - Webhooks, API, repository management
Security Audit Specialist - API keys, permissions, security checks
Docker Services Specialist - Service management, troubleshooting
Phase 3 Implementation Specialist - Autonomous build test MVP

Usage:

Task(
  subagent_type='general-purpose',
  description='n8n Workflow Specialist',
  model='sonnet',
  prompt='[specialized prompt with project knowledge]'
)

See: agent-templates.md for copy-paste ready templates Guide: custom-subagents-usage-guide.md for complete documentation

🎯 WORKING N8N WORKFLOW

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

Structure

[1] Gitea Webhook
     ↓
[2] Extract Repo Info (Code)
     ↓
[3] OpenHands Build (SSH)
     → sh /home/bam/openhands-sdk-wrapper-sh.sh "<task>"
     ↓
[4] Wait 10s
     ↓
[5] Check Build Status (Code) - uses $node pattern
     ↓
[6] Format Response (Code)
     ↓
[7] HTTP Response

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

Production-ready autonomous CI/CD with retry logic, error feedback, and Gitea status updates.

Workflow: 11-Node Design

[1] Git Push (Gitea webhook)
     ↓
[2] Extract commit info
     ↓
[3] Start OpenHands Build
     ↓
[4] Wait for completion
     ↓
[5] Check build results
     ↓
[6] Decision: Build OK?
     ├─ YES → Update Gitea → Success notification
     └─ NO → Format errors → Retry check → Retry or Fail

Key Components

A. Retry 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 Feedback

const errors = sshOutput.stderr || sshOutput.stdout;
return {
  status: 'FAILED',
  error_message: `Build failed:\n${errors}\nPlease fix.`,
  retry_count: $workflow.staticData.retry_count
};

C. Gitea Status Update

POST https://git.oky.sh/api/v1/repos/{owner}/{repo}/statuses/{sha}
Authorization: token {GITEA_TOKEN}
Body: {"state": "success", "description": "Build passed"}

Success Criteria

End-to-end workflow completes
OpenHands executes autonomously
Retry logic (max 3 attempts)
Error feedback to OpenHands
Gitea commit status updated
Tested with real project

Complete Details: See phase3.md (11 implementation steps, 4-5 hours)

🔑 N8N API REFERENCE

See: n8n-api.md for complete documentation

Quick Operations

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

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

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

📚 REFERENCE COMMANDS

Service Management

# Status
cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps

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

# Logs
docker logs -f n8n
docker logs -f caddy
docker logs -f gitea

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

Testing

See: /home/bam/claude/mvp-factory/test-scripts/README.md

🔐 CREDENTIALS

n8n: https://n8n.oky.sh (User: admin)
Gitea: https://git.oky.sh (Admin account)

API Keys

OpenHands (MiniMax):  /home/bam/openhands/.env → MINIMAX_API_KEY
OpenHands (DeepSeek): /home/bam/openhands/.env → DEEPSEEK_API_KEY
n8n API:              /home/bam/.n8n_api_key (JWT)
SSH Key:              /home/bam/.ssh/n8n_key
Gitea API:            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

n8n Data Flow

SSH nodes overwrite ALL data → Use $node["Previous Node"].json
passThrough: true does NOT preserve input
Code nodes preserve data by merging with previous output

Best Practices

Use $node pattern for data preservation
Test SDK scripts before n8n integration
Keep API keys secure (permissions 600)
Implement max retry limits (prevent infinite loops)
Update Gitea commit status for visibility

🏆 PROJECT STATUS

✅ Complete

Phase 1: Infrastructure Setup
- Gitea, n8n, Caddy running with SSL
- Docker compose configured
- SSH authentication working
Phase 2: OpenHands Integration (SDK)
- SDK wrapper created & tested
- n8n workflow integrated
- Build/test cycle functional
- Data preservation fixed
- Repository cleaned up (7 files removed)
- Testing infrastructure created
- Details: phase2.md

🎯 In Progress

Phase 3: Autonomous Build Test MVP

Retry logic with error feedback
Gitea commit status updates
Real project build testing
Plan: phase3.md

🎉 FINAL STATUS

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

Current Goal: Build Phase 3 - Autonomous Build Test MVP

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

9.6 KiB Raw Blame History