NomadCode Core

NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 저장하며, 비동기 Agent 작업 흐름을 관리하기 위한 서버입니다.

초기 목표는 작업 생성과 조회, PostgreSQL 기반 작업 상태 저장, River 기반 비동기 작업 실행, Plane/Mattermost Adapter stub 구성, 이후 IOP / Agent Integrator와 연결 가능한 구조 확보입니다.

현재 구현 범위

• Go HTTP Server
• GET /healthz, GET /readyz
• task 생성 / 조회 / 목록 / enqueue API
• PostgreSQL 연결
• goose migration
• sqlc 기반 DB query 생성 구조
• River dummy job
• Plane Adapter stub
• Mattermost Adapter stub
• 선택적 Docker Compose 실행 환경

현재 구현하지 않은 범위

• 실제 Plane API 호출
• 실제 Mattermost 메시지 발송
• IOP 연동
• Agent Integrator 연동
• Outline / Forgejo / Nextcloud 연동
• MCP 서버
• Web Agent UI
• Flutter 앱
• 복잡한 권한 정책
• 복잡한 workflow DSL

단계별 다음 작업

Phase 1. Server Skeleton

현재 스캐폴드 단계입니다.

목표:

• 서버 실행 골격 구성
• task 저장 구조 구성
• dummy 비동기 job 실행
• Adapter stub 생성

Phase 2. Workflow Core

목표:

• task 상태 전이 정리
• enqueue / running / completed / failed 흐름 안정화
• retry / timeout 기본 구조 추가
• notification event 구조 정리

Phase 3. External Integration

목표:

• Plane issue 생성 / comment / status update 구현
• Mattermost 메시지 발송 구현
• Agent Integrator 호출 구조 추가
• IOP 호출 구조 추가

실행 방법

로컬 실행은 호스트에 Go와 PostgreSQL이 설치되어 있다는 전제로 진행합니다. 기본 DATABASE_URL은 postgres://nomadcode:nomadcode@localhost:5432/nomadcode?sslmode=disable 입니다.

PostgreSQL 사용자와 DB 생성 예시:

psql postgres -c "CREATE USER nomadcode WITH PASSWORD 'nomadcode';"
psql postgres -c "CREATE DATABASE nomadcode OWNER nomadcode;"

Migration 실행:

./bin/migrate-up

서버 실행:

./bin/run

다른 DB 주소를 사용할 경우:

DATABASE_URL="postgres://user:password@localhost:5432/dbname?sslmode=disable" ./bin/migrate-up
DATABASE_URL="postgres://user:password@localhost:5432/dbname?sslmode=disable" ./bin/run

테스트 실행:

./bin/test

sqlc 실행:

./bin/sqlc

DB 접근 코드는 migrations/의 스키마와 queries/의 SQL을 기준으로 internal/db/에 생성합니다. internal/db/db.go, internal/db/models.go, internal/db/tasks.sql.go는 생성 파일이므로 직접 수정하지 않습니다.

Docker Compose 실행은 통합 확인이 필요할 때 선택적으로 사용합니다.

./bin/docker-up

Makefile은 같은 명령을 감싸는 얇은 alias입니다.

make migrate-up
make run
make test
make sqlc

API 테스트:

curl localhost:8080/healthz
curl localhost:8080/readyz

curl -X POST localhost:8080/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"README 수정 작업","source":"manual","payload":{"message":"README 초안을 정리해줘"}}'

curl localhost:8080/api/tasks
curl localhost:8080/api/tasks/{id}
curl -X POST localhost:8080/api/tasks/{id}/enqueue