Metadata-Version: 2.4
Name: aos-git
Version: 0.4.3
Summary: AI-powered Git merge conflict resolver — let AI merge both sides intelligently
License: MIT
Project-URL: Homepage, http://mod.lge.com/hub/esdataplfm/part_de/aos-git.git
Project-URL: Issues, http://mod.lge.com/hub/esdataplfm/part_de/aos-git.git/issues
Keywords: git,merge,conflict,ai,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: toml>=0.10
Requires-Dist: openai>=1.0
Requires-Dist: anthropic>=0.25

# aos — AI-powered Git Helper

`aos`는 git을 잘 모르는 팀원도 쉽게 사용할 수 있도록 만든 AI 기반 CLI 도구입니다.
브랜치 병합 중 충돌이 발생하면 AI가 양쪽 변경사항을 분석하여 **둘 다 살리는 방향으로 자동 통합**합니다.

---

## 목차

1. [설치](#설치)
2. [최초 설정](#최초-설정)
3. [팀 워크플로우 개요](#팀-워크플로우-개요)
4. [명령어 전체 목록](#명령어-전체-목록)
5. [시나리오별 사용법](#시나리오별-사용법)
6. [GitLab 이메일 알림 설정](#gitlab-이메일-알림-설정)
7. [설정 변경](#설정-변경)
8. [AI 제공자](#ai-제공자)
9. [요구사항](#요구사항)

---

## 설치

```bash
pip install aos-git
```

---

## 최초 설정

프로젝트 루트 디렉토리에서 1회 실행합니다.

```bash
aos setup
```

순서대로 아래 항목을 입력합니다.

| 항목 | 설명 |
|------|------|
| AI 제공자 | `databricks` 또는 `anthropic` |
| Databricks Host / Token | Databricks 사용 시 입력 |
| Anthropic API Key | Anthropic 사용 시 입력 |
| 안내 메시지 언어 | `ko` (한국어) 또는 `en` (영어) |
| GitLab 이메일 알림 | 알림 받을 브랜치 이름 + 수신자 이메일 목록 |

설정값은 `~/.aos/config.toml`에 저장됩니다.
알림 설정 시 프로젝트 루트에 `.gitlab-ci.yml`과 `scripts/notify_config.toml`이 자동 생성됩니다.

> **git merge.conflictstyle=diff3** 도 자동으로 전역 설정됩니다.
> AI가 BASE(공통 조상) 코드까지 참고하여 더 정확한 병합을 수행합니다.

---

## 팀 워크플로우 개요

```
[병합 관리자]                     [팀원 A, B, C ...]
     │                                   │
  각자 feature 브랜치에서 작업           │
     │                                   │
  aos merge feature/xxx  ──────────────  │
  (충돌 시 AI 자동 해결 + 커밋)          │
     │                                   │
  aos push (main 업데이트)               │
     │                                   │
  GitLab CI 자동 실행                    │
     │                                   │
  이메일 알림 발송 ─────────────→  aos sync 실행
                                  (최신 main 반영 + 충돌 시 AI 자동 해결 + 커밋)
```

---

## 명령어 전체 목록

### `aos setup`
AI 및 알림 설정을 초기화합니다.

```bash
aos setup             # 전체 설정 (최초 1회 또는 AI 설정 변경 시)
aos setup --notify    # 알림 설정만 변경 (수신자 추가/제거, 브랜치 변경 등)
```

---

### `aos branch`
브랜치 목록을 보기 좋게 출력합니다.

```bash
aos branch        # 로컬 브랜치 목록
aos branch -a     # 원격 브랜치 포함 전체 목록 (자동 fetch)
aos branch -d feature/xxx   # 브랜치 삭제
```

---

### `aos checkout`
브랜치를 이동하거나 새로 만듭니다.

```bash
aos checkout main              # 브랜치 이동 (없으면 원격에서 자동 가져옴)
aos checkout feature/my-work   # 원격 브랜치도 자동으로 로컬에 생성 후 이동
aos checkout -b feature/new    # 새 브랜치 생성
aos checkout -b feature/new --push   # 새 브랜치 생성 + 원격에 즉시 push
```

---

### `aos add`
변경된 파일을 스테이징합니다.

```bash
aos add                  # 변경된 파일 전체 스테이징
aos add src/main.py      # 특정 파일만 스테이징
aos add src/ tests/      # 여러 경로 지정
```

---

### `aos commit`
스테이징된 파일을 커밋합니다.

```bash
aos commit -m "feat: 기능 설명"
```

---

### `aos push`
현재 브랜치를 원격에 push합니다.

```bash
aos push
```

---

### `aos pull`
현재 브랜치에 원격 변경사항을 가져옵니다. 충돌 시 AI가 자동 해결합니다.

```bash
aos pull
```

---

### `aos status`
현재 작업 상태를 보여줍니다.

```bash
aos status
```

---

### `aos merge`
다른 브랜치를 현재 브랜치에 병합합니다.
충돌 발생 시 AI가 자동으로 해결하고 커밋까지 완료합니다.

```bash
aos merge feature/my-work          # 로컬 브랜치 병합
aos merge origin/feature/my-work   # 원격 브랜치 병합 (자동 fetch)
aos merge feature/my-work --no-fetch   # fetch 없이 바로 병합
```

충돌 해결 흐름:
```
충돌 감지
  └─→ AI가 BASE / OURS / THEIRS + 타임스탬프 분석
        └─→ 통합 결과 미리보기 출력
              └─→ [y] 적용  [N] 건너뜀  [e] 직접 편집
                    └─→ 모든 충돌 해결 완료 → 자동 커밋
```

---

### `aos sync`
최신 main(또는 지정 브랜치)을 현재 브랜치에 반영합니다.
병합 관리자가 main을 업데이트한 후 팀원이 실행합니다.
충돌 발생 시 AI가 자동으로 해결하고 커밋까지 완료합니다.

```bash
aos sync              # origin/main → 현재 브랜치에 반영
aos sync --base dev   # origin/dev 기준으로 반영
```

---

## 시나리오별 사용법

### A. 팀원 — 일상적인 작업

```bash
# 1. 작업 브랜치로 이동 (없으면 자동으로 원격에서 가져옴)
aos checkout feature/my-work

# 2. 파일 수정 후 저장
aos add
aos commit -m "feat: 기능 추가"
aos push

# 3. 병합 관리자로부터 이메일 알림 수신 후 → 최신 main 반영
aos sync
aos push
```

---

### B. 팀원 — 새 작업 시작

```bash
# 최신 main 기준으로 새 브랜치 생성
aos checkout main
aos pull
aos checkout -b feature/new-feature --push
```

---

### C. 병합 관리자 — main 업데이트

```bash
# 팀원 브랜치를 main에 병합
aos checkout main
aos merge feature/team-member-work
# 충돌이 있으면 AI가 자동 해결 후 커밋까지 완료

# main에 push → GitLab CI 실행 → 팀원에게 이메일 자동 발송
aos push
```

---

### D. 원격 브랜치 목록 확인 후 이동

```bash
aos branch -a
# ┌──────────────────────────────────┐
# │  * main                          │
# │    feature/data-pipeline         │
# │    origin/feature/report-ui      │
# └──────────────────────────────────┘

aos checkout feature/report-ui   # 원격 브랜치도 자동으로 로컬 생성 후 이동
```

---

## GitLab 이메일 알림 설정

`aos setup` 실행 시 알림 설정을 함께 완료하면 아래 파일이 자동 생성됩니다.

| 파일 | 역할 |
|------|------|
| `.gitlab-ci.yml` | 지정 브랜치 push 시 알림 스크립트 실행 |
| `scripts/notify_config.toml` | 수신자 이메일 목록 저장 |
| `scripts/notify_main_update.py` | 이메일 발송 스크립트 (자동 포함) |

생성 후 한 번만 커밋하면 이후 자동 동작합니다.

```bash
git add .gitlab-ci.yml scripts/notify_config.toml
aos commit -m "chore: add gitlab notify config"
aos push
```

**알림 이메일 예시**
```
제목: [aos-git] main 브랜치가 업데이트됐습니다 (a1b2c3d4)

main 브랜치에 새로운 변경사항이 병합됐습니다.
각자 브랜치에서 아래 명령어를 실행하여 최신 버전을 반영해주세요.

  aos sync
  aos commit -m "sync with main"
  aos push

──────────────────────────────
업데이트 정보
  작업자  : 이과장
  커밋    : a1b2c3d4 — merge: feature/data-pipeline
  프로젝트: https://gitlab.example.com/project
──────────────────────────────
```

---

## 설정 변경

### AI 설정 전체 변경
```bash
aos setup
```
이전 설정값이 기본값으로 표시되므로 변경이 필요한 항목만 입력하고 나머지는 Enter로 유지할 수 있습니다.

### 알림 설정만 변경 (수신자 추가/제거, 브랜치 변경)
```bash
aos setup --notify
```
```
[aos] GitLab 알림 설정
  현재 브랜치  : main
  현재 수신자  : kim@lge.com, park@lge.com

알림을 받을 브랜치 이름 [main]:
수신자 이메일 [kim@lge.com, park@lge.com]: kim@lge.com,park@lge.com,lee@lge.com

[aos] .gitlab-ci.yml 생성됨 (브랜치: main)
[aos] scripts/notify_config.toml 생성됨
```

변경 후 커밋·push 하면 즉시 반영됩니다.

```bash
git add .gitlab-ci.yml scripts/notify_config.toml
aos commit -m "chore: update notify recipients"
aos push
```

---

## AI 제공자

### Databricks Model Serving (기본)
사내 Databricks 환경을 사용합니다.

```toml
# ~/.aos/config.toml
[ai]
provider = "databricks"
model = "databricks-claude-sonnet-4-6"

[databricks]
host = "https://adb-xxxx.azuredatabricks.net"
token = "dapi..."
```

### Anthropic API
```toml
[ai]
provider = "anthropic"
model = "claude-sonnet-4-6"

[anthropic]
api_key = "sk-ant-..."
```

---

## 새 버전 릴리스 (관리자용)

GitLab CI가 `v*` 형식의 태그를 감지하면 자동으로 PyPI에 배포합니다.

### 1회 사전 준비 — PyPI 토큰 등록

GitLab 프로젝트 → **Settings → CI/CD → Variables** 에서 추가:

| Key | Value | Options |
|-----|-------|---------|
| `PYPI_API_TOKEN` | PyPI에서 발급한 API 토큰 (`pypi-...`) | Masked 체크 |

### 배포 방법

```bash
# 방법 1: 스크립트 사용 (권장)
./scripts/release.sh 0.4.0
# pyproject.toml 버전 수정 → 커밋 → 태그 생성 → push 까지 자동 처리

# 방법 2: 수동
# 1) pyproject.toml의 version = "0.4.0" 으로 수정
# 2) git add pyproject.toml && git commit -m "chore: release v0.4.0"
# 3) git tag v0.4.0
# 4) git push origin HEAD && git push origin v0.4.0
```

push 후 GitLab **CI/CD → Pipelines** 에서 배포 진행 상황을 확인할 수 있습니다.

---

## 요구사항

- Python 3.11+
- git
- Databricks Model Serving 접근 권한 **또는** Anthropic API 키
