npm package: @imprun/cli
Description: Official CLI for imprun.dev development
Author: imprun.dev team
Latest version: 1.0.0

# @imprun/cli

Official CLI for imprun.dev CloudFunction development

**로컬 개발 전용 도구** - 로컬에서 CloudFunction을 개발하고 dev 환경에 배포합니다.

## 설치

```bash
npm install -g @imprun/cli
```

## 빠른 시작

### 1. 로그인

```bash
imp auth login
```

브라우저에서 GitHub OAuth로 인증합니다.

### 2. 새 Function 프로젝트 초기화

```bash
mkdir my-function && cd my-function
imp init

# 또는 직접 지정
imp init --gateway gateway-123 --function login
```

### 3. 코드 작성

```typescript
// src/index.ts
export async function handler(ctx: any) {
  return { message: "Hello, World!" };
}
```

### 4. 배포 (dev 환경)

```bash
# 기본 배포
imp push

# 버전 지정하여 배포
imp push --semver 1.2.0

# 메시지와 함께 배포
imp push --semver 1.2.0 -m "Add authentication"
```

서버가 자동으로 컴파일하고 K8s에 배포합니다.

## 주요 명령어

### Core Commands

| 명령어 | 설명 |
|--------|------|
| `imp init` | 새 Function 프로젝트 초기화 |
| `imp clone` | 서버에서 기존 Function 복제 |
| `imp push [options]` | 서버에 배포 (자동으로 dev 환경) |
| `imp pull` | 서버에서 최신 코드 가져오기 |

**push 옵션:**
- `-s, --semver <version>`: Semantic version 설정 (예: 1.2.0)
- `-m, --message <message>`: 변경사항 설명
- `-f, --force`: 확인 없이 즉시 배포

### Auth Commands

| 명령어 | 설명 |
|--------|------|
| `imp auth login` | GitHub OAuth 로그인 |
| `imp auth logout` | 로그아웃 |
| `imp whoami` | 현재 사용자 정보 |

### Dev Commands

| 명령어 | 설명 |
|--------|------|
| `imp run` | 로컬에서 Function 실행 |

### 기타

```bash
imp --version    # CLI 버전 확인
imp --help       # 도움말
```

### Verbose 옵션 (디버깅)

HTTP 통신 및 상세 로그를 보려면 `-v` 옵션을 사용하세요:

```bash
# 기본 정보 로그
imp push -v

# HTTP 요청/응답 표시
imp push -vv

# 전체 요청/응답 body 포함
imp push -vvv

# 다른 명령어에도 적용 가능
imp clone -vv --gateway gateway-123 --function login
imp pull -vvv
```

**Verbose 레벨**:
- `-v` (INFO): 주요 작업 정보
- `-vv` (DEBUG): HTTP 요청/응답 헤더
- `-vvv` (TRACE): 전체 요청/응답 body 포함

## 개발 워크플로우

### 1. 새 Function 개발

```bash
# 프로젝트 생성
mkdir my-function && cd my-function
imp init --gateway gateway-123 --function login

# 코드 작성
# src/index.ts 편집...

# 배포 (초기 버전)
imp push --semver 0.1.0

# 웹 포털에서 확인
# https://portal.imprun.dev
```

### 2. 기존 Function 수정

```bash
# Function 복제
imp clone --gateway gateway-123 --function login

# 코드 수정
# ...

# 버그 수정 - Patch 버전 업
imp push --semver 0.1.1 -m "Fix login bug"

# 새 기능 - Minor 버전 업
imp push --semver 0.2.0 -m "Add OAuth support"

# Breaking change - Major 버전 업
imp push --semver 1.0.0 -m "Redesign API"
```

### 3. 팀 협업 (Git 사용)

```bash
# 팀원 A
git clone https://github.com/team/my-function
cd my-function
imp pull          # 서버에서 최신 코드 동기화
# ... 코드 수정 ...
imp push --semver 0.3.0
git add . && git commit -m "feat: add validation"
git push

# 팀원 B
git pull          # Git에서 최신 코드 가져오기
imp pull          # 서버와 동기화
# ... 코드 수정 ...
imp push --semver 0.3.1
git add . && git commit -m "fix: bug fix"
git push
```

## 핵심 개념

### Function 이름 규칙

CLI에서 입력한 Function 이름은 서버에서 자동으로 `dev/` prefix가 추가됩니다:

```bash
imp init --function login
# → 서버에 "dev/login"으로 저장
# → URL: https://gateway-123.api.imprun.dev/dev/login
```

### Semantic Versioning

모든 Function은 semantic version이 필수입니다:

```bash
# function.json에서 직접 수정하거나
vim .imp/function.json

# push 시 CLI 옵션으로 설정
imp push --semver 1.2.0
```

형식: `Major.Minor.Patch` (예: 1.0.0, 1.2.3, 2.0.0)

**버전 관리 권장사항:**
- **Patch** (0.0.x): 버그 수정, 내부 리팩토링
- **Minor** (0.x.0): 새 기능 추가 (하위 호환)
- **Major** (x.0.0): Breaking changes

### 파일 스캔 규칙

프로젝트 루트에서 재귀적으로 모든 `.ts`, `.js` 파일을 스캔합니다.

**포함**:
- `src/`, `lib/`, `utils/` 등 모든 소스 파일

**제외**:
- `node_modules/`, `dist/`, `.git/`, `.imp/`
- `build/`, `coverage/`, `.vscode/`

### .imp/function.json 구조

```json
{
  "gatewayId": "gateway-123",
  "gatewayName": "My Gateway",
  "functionName": "dev/login",
  "semver": "1.0.0",
  "entrypoint": "src/index.ts",
  "methods": ["GET", "POST"],
  "tags": ["auth"],
  "description": "User login endpoint",
  "_fileHashes": {},
  "_lastPushAt": "2025-01-20T10:30:00.000Z"
}
```

## 소스 관리

### Git 사용 권장

CLI는 **로컬 개발 도구**입니다. 소스 관리는 Git을 사용하세요:

```bash
# Git 초기화
git init
git add .
git commit -m "Initial commit"

# 리모트 연결
git remote add origin https://github.com/user/my-function
git push -u origin main

# 팀원과 협업
git pull
imp pull          # 서버와도 동기화
# ... 개발 ...
imp push --semver 1.1.0
git add . && git commit -m "Update"
git push
```

### 이력 관리

- **배포 히스토리**: 웹 포털에서 확인
- **코드 변경 이력**: Git 사용
- **버전 관리**: `imp push --semver`로 관리

## 환경 구성

### API 서버 URL

기본값: `http://localhost:3000`

변경 방법:
```bash
# 환경변수
export IMPRUN_API_URL=https://api.imprun.dev

# CLI 옵션
imp --api-url https://api.imprun.dev push
```

### 프로덕션 배포

CLI는 **dev 환경 전용**입니다.

staging/prod 배포는 **웹 포털**에서 수행하세요:
1. 웹 포털 로그인
2. Function 선택
3. "Promote to Staging/Prod" 버튼 클릭

## 문제 해결

### 로그인 실패

```bash
imp auth logout
imp auth login
```

### push 시 "변경사항 없음"

강제 배포:
```bash
imp push -f
```

### pull 시 "로컬 변경사항" 경고

로컬 변경사항 무시:
```bash
imp pull -f
```

### Function이 서버에 없음

초기 push 필요:
```bash
imp push --semver 0.1.0
```

## 라이센스

MIT

## 기여

이슈와 PR은 [GitHub 저장소](https://github.com/imprun/imprun)에서 환영합니다.