Metadata-Version: 2.4
Name: aos-git
Version: 0.6.2
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
Requires-Dist: questionary>=2.0

# aos — AI-powered Git Helper

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

---

## 목차

1. [설치](#설치)
2. [최초 설정](#최초-설정)
3. [Claude Code 연동](#claude-code-연동)
4. [팀 워크플로우 개요](#팀-워크플로우-개요)
5. [명령어 전체 목록](#명령어-전체-목록)
6. [시나리오별 사용법](#시나리오별-사용법)
7. [이메일 알림 설정](#이메일-알림-설정)
8. [설정 변경](#설정-변경)
9. [AI 제공자](#ai-제공자)
10. [새 버전 릴리스](#새-버전-릴리스-관리자용)
11. [요구사항](#요구사항)

---

## 설치

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

---

## 최초 설정

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

```bash
aos setup
```

단계별 안내에 따라 아래 항목을 입력합니다.

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

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

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

---

## Claude Code 연동

`aos`를 Claude Code와 연동하면 `/aos` 슬래시 커맨드로 skill을 호출하고,
충돌 발생 시 Claude가 자동으로 `aos` 사용을 권장받습니다.

### 1단계 — 전역 skill 설치 (pip install 후 1회)

```bash
aos install
```

- `~/.claude/skills/aos/SKILL.md` 에 skill 파일 설치
- `~/.claude/CLAUDE.md` 에 `/aos` 트리거 등록

### 2단계 — 프로젝트별 연동 (저장소 루트에서 1회)

```bash
aos claude install
```

- 프로젝트 `CLAUDE.md` 에 aos 사용 규칙 추가
- `.claude/settings.json` 에 `PreToolUse` 훅 등록  
  → 충돌 파일이 감지되면 Claude에게 `aos merge` / `aos pull` 사용을 자동 안내

### 제거

```bash
aos claude uninstall   # 프로젝트 연동 제거
aos uninstall          # 전역 skill 제거
```

---

## 팀 워크플로우 개요

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

---

## 명령어 전체 목록

### `aos setup`

AI 및 알림 설정을 초기화합니다.

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

---

### `aos checkout`

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

```bash
# 인수 없이 실행하면 화살표 키로 브랜치를 선택하는 인터랙티브 UI가 표시됩니다
aos checkout

# 브랜치명을 직접 지정할 수도 있습니다
aos checkout main               # 브랜치 이동 (없으면 원격에서 자동 가져옴)
aos checkout feature/my-work    # 원격 브랜치도 자동으로 로컬 생성 후 이동
aos checkout -b feature/new     # 새 브랜치 생성
aos checkout -b feature/new --push   # 새 브랜치 생성 + 원격에 즉시 push
```

인터랙티브 선택 화면 예시:
```
? 전환할 브랜치를 선택하세요
❯ * main  (현재)
    feature/data-pipeline
    feature/report-ui
    origin/feature/remote-only  (원격)
```

---

### `aos branch`

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

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

---

### `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
# 또는
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 → pre-push hook 실행 → 팀원에게 이메일 자동 발송
aos push
```

---

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

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

# 이름을 입력하거나 인터랙티브 UI로 선택
aos checkout feature/report-ui
```

---

## 이메일 알림 설정

`aos setup` 또는 `aos setup --notify` 실행 시 알림 설정을 완료하면
`scripts/notify_config.toml`이 자동 생성됩니다.

| 파일 | 역할 |
|------|------|
| `scripts/notify_config.toml` | 수신자 이메일 목록 저장 |
| `.git/hooks/pre-push` | push 시 알림 스크립트 자동 실행 (symlink) |

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

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

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

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

  aos sync
  aos push

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

---

## 설정 변경

### AI 설정 전체 변경

```bash
aos setup
```

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

### 알림 설정만 변경 (수신자 추가/제거, 브랜치 변경)

```bash
aos setup --notify
```

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

```bash
git add 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
# 스크립트 사용 (권장)
./scripts/release.sh 0.5.0
# pyproject.toml 버전 수정 → 커밋 → 태그 생성 → push 까지 자동 처리
```

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

---

## 요구사항

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