# Gito

Gito는 agent-driven development를 위한 platformless Git control plane이다.
여러 Git platform의 공통 인터페이스를 제공해 repository registry,
workspace lease, Git operation, provider adapter, normalized event를 하나의
제어 흐름으로 묶는다. Agent interaction UI는 sibling `../agent-shell`
Flutter package를 사용하고, 그 UI를 구동하는 backend/runtime은 sibling
`../iop` 프로젝트가 맡는 방향으로 둔다.

Git 자체 작업은 GitHub/GitLab/Gitea 같은 플랫폼을 몰라도 동작해야 한다.
PR/MR, review, checks, webhook 같은 플랫폼 기능은 provider adapter 뒤에 둔다.
외부 연동은 GitHub webhook과 유사한 HTTP webhook/callback 모델을 기본으로
하고, Gito 전용 binary transport를 요구하지 않는다.

## 현재 상태

초기 scaffold 단계다. Go core는 build/test 가능한 최소 골격을 갖고 있고,
Flutter client는 control surface 경계만 잡혀 있다.

현재 가능한 범위:

- Go `server`, `worker` command build
- health/readiness REST placeholder
- 내부 proto-socket registry와 binary `event.subscribe` / `branch.updated` event path
- Forgejo push callback, watched branch listener, branch event smoke/debug surface
- PostgreSQL-backed repo, workspace lease, operation, event, branch watch, revision cursor, provider delivery baseline
- platformless `gitengine` 최소 테스트
- core domain DTO 후보
- provider-neutral `ChangeRequest` adapter 경계
- Postgres migration 초기안
- `agent-ops` 규칙/스킬 기반 작업 진입점

아직 구현 전인 범위:

- `event` 외 내부 proto-socket channel/action의 실제 command behavior
- `agent_shell: path: ../agent-shell` package를 쓰는 Flutter host
  integration
- `../iop` backend/runtime 결과를 Gito operation/event 계약으로 수렴시키는
  연결
- 외부 consumer용 HTTP webhook delivery registration과 retry/outbox dispatch
- GitHub/GitLab/Gitea provider adapter와 Forgejo PR/MR adapter
- Flutter 화면 구성과 operation event 구독

## 빠른 시작

```sh
bin/test
bin/lint
bin/build
```

빌드가 끝나면 root `bin/` 아래에 아래 실행 파일이 생성된다.

```text
bin/gito-server
bin/gito-worker
```

서버 scaffold 실행:

```sh
HTTP_ADDR=:8080 bin/gito-server
```

확인:

```sh
curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz
```

## 주요 명령

| 목적 | 명령 | 비고 |
| --- | --- | --- |
| 전체 테스트 | `bin/test` | Go test 실행, Flutter test scaffold가 없으면 client test는 skip |
| lint | `bin/lint` | `go vet ./...`, Flutter가 있으면 `flutter analyze --no-fatal-infos` |
| build | `bin/build` | `gito-server`, `gito-worker` 생성 |
| Core test | `cd services/core && go test ./...` | Go module 기준 직접 실행 |
| Core lint | `cd services/core && go vet ./...` | Go vet 직접 실행 |

## 구조

| 경로 | 역할 |
| --- | --- |
| `services/core/cmd/server/` | control plane server entrypoint |
| `services/core/cmd/worker/` | operation worker entrypoint |
| `services/core/internal/controlplane/` | REST API/webhook surface, internal proto-socket surface, auth/policy gate 후보 |
| `services/core/internal/core/` | provider-neutral domain model |
| `services/core/internal/gitengine/` | platformless Git operation layer |
| `services/core/internal/worker/` | operation 실행 orchestration 후보 |
| `services/core/internal/provider/` | GitHub/GitLab/Gitea/Plane/Jira adapter boundary |
| `services/core/internal/events/` | normalized event model |
| `services/core/internal/storage/` | PostgreSQL store boundary |
| `services/core/migrations/` | database schema migration |
| `apps/client/` | Flutter control surface scaffold |
| `packages/contracts/` | HTTP webhook/REST, internal proto-socket, event, DTO contract notes |
| `docs/` | 사람용 architecture/operation 문서 |
| `agent-ops/` | agent rules, skills, roadmap helper |
| `agent-test/` | local validation rules |

## 설계 방향

Gito는 처음에는 modular monolith로 시작하되, 실행 역할은 분리 가능하게 둔다.

```text
Flutter UI / gitoctl
        |
Control Plane
        |
Core Domain
        |
Worker / Scheduler
        |
IOP backend/runtime + Git Engine
        |
Provider Adapters
```

원칙:

- `controlplane`은 요청, 정책, 관찰, event stream을 소유한다.
- `core`는 repo, workspace lease, operation, revision cursor, event 원장을 소유한다.
- `worker`는 operation 실행과 외부 runtime 결과 수렴을 조율한다.
- Flutter host는 `agent_shell: path: ../agent-shell` dependency로 agent
  interaction UI/domain package를 붙인다.
- `../agent-shell`은 Flutter agent UI/package이며 Gito backend가 아니다.
- `../iop`는 agent backend/runtime을 맡고, Gito는 그 결과를 Git operation과
  event 원장으로 수렴한다.
- `gitengine`은 platformless여야 하며 local bare repo만으로 테스트 가능해야 한다.
- `provider`는 PR/MR/review/checks/webhook 같은 플랫폼 기능만 맡는다.
- 외부 시스템은 GitHub webhook과 비슷한 HTTP webhook/callback으로 연결한다.
- proto-socket은 내부 control/runtime surface로만 사용하고, 외부 연결 규약이나
  보조 transport로 제공하지 않는다.
- PostgreSQL은 source of truth이고, Redis는 필요할 때 fanout/stream 가속 계층으로만 둔다.

## 통신 정책

- 외부 provider와 consumer 연동은 REST API와 HTTP webhook/callback을 사용한다.
- proto-socket은 내부 control/runtime 통신에만 사용한다.
- REST는 health/readiness, provider callback, external webhook delivery,
  smoke/curl, 단순 bootstrap에 둔다.
- gRPC는 초기 설계에서 제외한다.
- webhook은 빠른 wakeup signal로만 보고, 최종 판정은 Git revision/diff 또는 provider read API로 재검증한다.

## 작업 맥락

작업을 시작할 때는 먼저 [AGENTS.md](AGENTS.md)를 읽고, 변경 경로에 맞는 domain rule을 확인한다.

주요 문서:

- [Project rules](agent-ops/rules/project/rules.md)
- [Core domain rules](agent-ops/rules/project/domain/core/rules.md)
- [Client domain rules](agent-ops/rules/project/domain/client/rules.md)
- [Contracts domain rules](agent-ops/rules/project/domain/contracts/rules.md)
- [Workspace ops rules](agent-ops/rules/project/domain/workspace-ops/rules.md)
- [Local test rules](agent-test/local/rules.md)
- [Architecture](docs/architecture.md)
- [Control plane contract candidates](packages/contracts/notes/gito-control-plane.md)

## 개발 흐름

1. 변경 전에 관련 domain rule을 읽는다.
2. core 변경은 `cd services/core && go test ./...` 또는 `bin/test`로 확인한다.
3. contracts 변경은 README/notes의 transport 정책과 맞는지 확인한다.
4. client 변경은 Flutter toolchain이 있으면 `flutter analyze --no-fatal-infos`와 `flutter test`를 실행한다.
5. 생성된 binary, `.dart_tool/`, local secret 파일은 commit하지 않는다.

## 환경 변수

| 이름 | 설명 | 필수 |
| --- | --- | --- |
| `APP_ENV` | runtime 환경 이름, 기본값 `local` | 아니오 |
| `HTTP_ADDR` | server listen address, 기본값 `:8080` | 아니오 |
| `DATABASE_URL` | PostgreSQL connection string, 없으면 in-memory runtime 사용 | 아니오 |
| `REDIS_URL` | optional Redis endpoint | 아니오 |
| `PROTO_SOCKET_PATH` | proto-socket endpoint path, 기본값 `/proto-socket` | 아니오 |
| `FORGEJO_WEBHOOK_SECRET` | Forgejo push callback HMAC-SHA256 서명 키, 없으면 검증 생략 | 아니오 |
| `WORKER_ENABLED` | worker 실행 여부, 기본값 `true` | 아니오 |

Credential 값은 tracked 파일에 쓰지 않는다. 필요한 경우 `credential_ref`나 ignored local secret file로 연결한다.

## 참고 문서

- [docs/architecture.md](docs/architecture.md)
- [packages/contracts/notes/gito-control-plane.md](packages/contracts/notes/gito-control-plane.md)
- [agent-ops/skills/common/create-readme/SKILL.md](agent-ops/skills/common/create-readme/SKILL.md)