kitech-repository 0.5.4
KITECH Manufacturing Data Repository CLI and Library
Requires Python: >=3.10
Keywords: cli, data, file-manager, kitech, manufacturing, repository, tui

# KITECH Manufacturing Data Repository CLI

KITECH 제조 데이터 리포지토리를 위한 Python CLI 도구 및 라이브러리입니다.

## 기능

- 🖥️ **대화형 파일 관리자 (TUI)** - Textual 프레임워크 기반 현대적인 TUI
  - 리포지토리 선택 화면 (페이지네이션 지원)
  - 듀얼 패널 파일 관리자 (로컬 ↔ 리포지토리)
  - 향상된 포커스 관리 (시각적 표시기)
  - 실시간 진행률 추적 (업로드/다운로드)
  - 배치 작업 지원 (여러 파일 동시 처리)
- 🔐 APP Key 기반 인증 (파일 권한 600으로 보호)
- ⬇️ 파일/폴더 다운로드 (SHA-256 무결성 검증)
- ⬆️ 파일/폴더 업로드 (MD5 무결성 검증, **100MB 제한**)
- 📊 실시간 진행률 표시 (배치 작업 지원)
- ⚡ 최적화된 검증 순서 (빠른 실패로 성능 향상)
- 🐍 Python Library API (프로그래밍 방식 사용 가능)

## 요구 사항

- Python 3.10 ~ 3.13
- pip 또는 pipx

## 설치

### CLI만 사용하는 경우 (pipx 권장)

CLI 명령어만 사용하려면 pipx로 설치하세요:

```bash
# pipx 설치 (한 번만)
brew install pipx
pipx ensurepath

# kitech-repository 설치
pipx install kitech-repository
```

### CLI + Library 함께 사용하는 경우 (pip 권장)

Python 프로그램에서 라이브러리로도 사용하려면 pip로 설치하세요:

```bash
# 가상환경에서 설치 (권장)
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install kitech-repository

# 또는 사용자 설치
pip install --user kitech-repository
```

**참고**: pipx로 설치하면 CLI만 사용 가능하며, Python 코드에서 `from kitech_repository import ...` 같은 라이브러리 import를 할 수 없습니다.

## 사용법

### 1. 초기 설정 (간단 버전)

단 한 번의 명령으로 서버 설정 + 로그인을 완료할 수 있습니다:

```bash
# 대화형으로 설정 (서버 URL과 APP Key를 순서대로 입력)
kitech login

# 또는 직접 지정
kitech login https://your-server.com
```

이 명령은 서버 주소를 설정하고 APP Key 로그인까지 한 번에 처리합니다.

### 2. 파일 관리자 시작 

```bash
kitech start
```

실행하면 리포지토리 선택 화면이 먼저 나타납니다:

**1단계: \
리포지토리 선택 화면**
- 모든 접근 가능한 리포지토리 목록 표시 (페이지네이션 지원)
- `↑/↓` 키로 리포지토리 선택
- `Enter` 키를 눌러 해당 리포지토리의 파일 관리자로 진입

**2단계: 듀얼 패널 파일 관리자**
- **왼쪽 패널 (로컬)**: 로컬 파일 시스템
- **오른쪽 패널 (리포지토리)**: 선택한 리포지토리의 파일
- **하단 패널**: 파일 전송 진행률 표시

### 기본 사용 흐름

1. **파일 탐색**
   - `↑/↓` 키로 파일/폴더 선택
   - `Enter` 키로 폴더 열기 또는 파일 다운로드
   - `..` 항목을 선택하고 `Enter`를 눌러 상위 디렉토리로 이동
   - `Tab` 키로 왼쪽/오른쪽 패널 전환

2. **다운로드** (리포지토리 → 로컬)
   - 오른쪽 패널(리포지토리)에서 다운로드할 파일/폴더 선택
   - `Enter` 키 또는 `F2` 키로 선택한 파일 다운로드
   - `F1` 키로 현재 디렉토리의 모든 파일 다운로드
   - `~/Downloads` 폴더에 다운로드됨
   - 실시간 진행률이 하단에 표시됨

3. **업로드** (로컬 → 리포지토리)
   - 왼쪽 패널(로컬)에서 업로드할 파일/폴더 선택
   - `F4` 키로 선택한 파일 업로드
   - `F3` 키로 현재 디렉토리의 모든 파일 업로드
   - 오른쪽 패널의 현재 경로에 업로드됨
   - 실시간 진행률이 하단에 표시됨

4. **종료**
   - `Ctrl+C` 또는 `Ctrl+Q` 키로 프로그램 종료
   - 터미널에서 `kitech logout`으로 로그아웃

### 키보드 단축키

#### 전역 단축키

| 키 | 기능 |
|---|---|
| `Tab` | 왼쪽/오른쪽 패널 전환 |
| `Ctrl+C` / `Ctrl+Q` | 프로그램 종료 |

#### 로컬 패널 (왼쪽)

| 키 | 기능 |
|---|---|
| `↑/↓` | 파일/폴더 선택 |
| `Enter` | 폴더 열기 |
| `F3` | 현재 디렉토리의 모든 파일 업로드 |
| `F4` | 선택한 파일 업로드 |
| `F5` | 파일 목록 새로고침 |
| `Backspace` | 상위 디렉토리로 이동 |

#### 리포지토리 패널 (오른쪽)

| 키 | 기능 |
|---|---|
| `↑/↓` | 파일/폴더 선택 |
| `Enter` | 폴더 열기 또는 파일 다운로드 |
| `F1` | 현재 디렉토리의 모든 파일 다운로드 |
| `F2` | 선택한 파일 다운로드 |
| `F5` | 파일 목록 새로고침 |
| `Backspace` | 상위 디렉토리로 이동 |

## 명령어 참조

### 주요 명령어

```bash
# 로그인 (서버 설정 + 인증 한번에)
kitech login [SERVER_URL]

# 파일 관리자 시작
kitech start [REPO_ID]

# 연결 상태 확인
kitech status

# 로그아웃
kitech logout

# 버전 확인
kitech version
```

### 고급 명령어

```bash
# 서버 URL 변경
kitech server [NEW_URL]

# 현재 설정 확인
kitech config

# 설정 초기화
kitech config reset
```

### 저장 위치

- **설정 파일**: `~/.kitech/config.json` - 서버 URL, 청크 크기
- **인증 정보**: `~/.kitech/auth.json` - API 키, 사용자 정보, 만료일 (권한 600으로 보호)

### 환경 변수 (선택사항)

명령어 대신 환경 변수로도 설정할 수 있습니다:

```bash
# 환경 변수로 설정
export KITECH_API_BASE_URL=https://your-api-server.com

# 또는 .env 파일에 작성
echo "KITECH_API_BASE_URL=https://your-api-server.com" > .env
```

**주의**: 베이스 URL만 입력하세요. API 버전(`/v1`)은 클라이언트가 런타임에 자동으로 추가합니다.

---

## 개발자를 위한 Library API

Python 프로그램에서 직접 사용할 수 있습니다.

### 1. 로그인 및 연결

```python
from kitech_repository import KitechClient, Config
from dotenv import load_dotenv
import os

# .env 파일 로드
load_dotenv()

# Config 생성
config = Config(server_url=os.getenv("KITECH_SERVER_URL"))
APP_KEY = os.getenv("KITECH_APP_KEY")

# Client 생성 및 연결 테스트
client = KitechClient(config=config, app_key=APP_KEY)

try:
    result = client.test_connection()
    print("✓ Connected successfully!")
    print(f"Response: {result}")
except Exception as e:
    print("✗ Connection failed!")
    print(f"Error: {e}")

# Config 저장
config.save()
print("✓ Config 저장됨: ~/.kitech/config.json")
```

### 2. 리포지토리 목록 조회

```python
from kitech_repository import KitechClient

# 페이지네이션을 사용한 리포지토리 목록 조회
with KitechClient(app_key="kt_xxx") as client:
    result = client.list_repositories(page=0, limit=5)

    print(f"전체 리포지토리 수: {result['total_count']}")

    for repo in result["repositories"]:
        print(f"리포지토리 ID: {repo.id}")
        print(f"리포지토리 이름: {repo.name}")
        print(f"내 권한: {repo.user_role}")
        print(f"설명: {repo.description}")
        print("-------------------------")
```

### 3. 파일 다운로드

```python
from kitech_repository import KitechClient

# 전체 리포지토리 다운로드
with KitechClient(app_key="kt_xxx") as client:
    result = client.download(
        repository_id=123,
        remote_path="",  # 빈 문자열 = 전체 리포지토리
        local_path="./downloads/",
    )
    print(f"✓ 전체 다운로드 완료: {result}")

# 단일 파일 다운로드
with KitechClient(app_key="kt_xxx") as client:
    result = client.download(
        repository_id=123,
        remote_path="data/example.txt",
        local_path="./downloads/",
    )
    print(f"✓ 파일 다운로드 완료: {result}")

# 폴더 다운로드
with KitechClient(app_key="kt_xxx") as client:
    result = client.download(
        repository_id=123,
        remote_path="data/folder/",
        local_path="./downloads/",
    )
    print(f"✓ 폴더 다운로드 완료: {result}")
```

### 4. 파일 업로드

```python
from kitech_repository import KitechClient

# 단일 파일 업로드 (100MB 미만)
with KitechClient(app_key="kt_xxx") as client:
    result = client.upload(
        repository_id=123,
        local_path="./local_file.txt",
        remote_path="data/",
    )
    print("✓ 파일 업로드 완료")

# 폴더 업로드 (최대 5개 파일 동시 업로드)
with KitechClient(app_key="kt_xxx") as client:
    result = client.upload(
        repository_id=123,
        local_path="./my_folder/",
        remote_path="data/",
    )
    print("✓ 폴더 업로드 완료")
```