npm package: @kurly-growth/growthman
Description: Local mock API server with UI dashboard
Latest version: 0.1.35

# Growthman

로컬 개발용 Mock API 서버입니다. 웹 UI에서 Mock 엔드포인트를 등록하고 테스트할 수 있습니다.

## 주요 기능

- 웹 UI로 Mock API 엔드포인트 등록/수정/삭제
- OpenAPI 스펙 파일 임포트 (자동으로 Mock 엔드포인트 생성)
- Express 스타일 경로 파라미터 지원 (`:id` 등)
- 내장 API 테스트 기능
- Base URL 복사 기능
- SQLite 기반 데이터 영속화 (`~/.growthman/data.db`)

## 설치 및 실행

### npx로 바로 실행 (권장)

```bash
npx @kurly-growth/growthman
```

실행하면 자동으로 브라우저가 열립니다. 데이터는 `~/.growthman/` 디렉토리에 저장됩니다.

```bash
# 포트 지정
PORT=8080 npx @kurly-growth/growthman
```

### 전역 설치

```bash
npm install -g @kurly-growth/growthman
growthman
```

## 사용법

1. `http://localhost:3100` 접속
2. **"+ New Endpoint"** 버튼으로 Mock API 등록
   - Path: `/v1/users/:id` (Express 스타일 경로 지원)
   - Method: GET, POST, PUT, DELETE 등
   - Status Code: 200, 400, 500 등
   - Response Body: JSON 응답
3. `http://localhost:3100/api/mock/{등록한 경로}`로 요청
4. **"Import OpenAPI"** 버튼으로 OpenAPI 스펙 파일 일괄 임포트

## 프록시 기능

각 Mock 엔드포인트에는 `isMockEnabled` 플래그가 있으며, 이 값에 따라 Mock 응답과 프록시 동작이 결정됩니다.

### 동작 알고리즘

```
요청 수신
  │
  ├─ 매칭되는 엔드포인트 있음
  │   ├─ isMockEnabled = true  → Mock 응답 반환
  │   └─ isMockEnabled = false
  │       ├─ X-Growthman-Target 헤더 있음 → 대상 서버로 프록시
  │       └─ X-Growthman-Target 헤더 없음 → Mock 응답 반환 (fallback)
  │
  └─ 매칭되는 엔드포인트 없음
      ├─ X-Growthman-Target 헤더 있음 → 대상 서버로 프록시
      └─ X-Growthman-Target 헤더 없음 → 404 반환
```

- **Mock 모드** (`isMockEnabled = true`): 항상 저장된 Mock 응답을 반환합니다.
- **프록시 모드** (`isMockEnabled = false`): `X-Growthman-Target` 헤더에 지정된 서버로 요청을 프록시합니다. 헤더가 없으면 Mock 응답으로 fallback합니다.
- 프록시된 응답에는 `X-Growthman-Proxied: true` 헤더가 추가됩니다.

## 로컬 네트워크 서비스 등록 (DNS-SD)

서버 시작 시 macOS 환경에서 `dns-sd`를 사용하여 로컬 네트워크에 서비스를 자동 등록합니다. 같은 네트워크의 다른 기기(모바일 등)에서 별도 IP 설정 없이 Growthman 서버에 접근할 수 있습니다.

```bash
# 등록되는 서비스 정보
# 서비스명: growthman-{사용자명} (CLI 최초 실행 시 입력)
# 타입: _http._tcp
# 포트: 3100 (또는 PORT 환경변수 값)
```

### 서비스 이름 설정

CLI(`growthman`) 최초 실행 시 서비스 이름을 입력받으며, 이후 실행에서는 저장된 이름을 자동으로 사용합니다. 같은 네트워크에서 여러 개발자가 서비스를 구분할 수 있습니다.

```bash
# 서비스 이름 재설정 (다음 실행 시 다시 입력 프롬프트 표시)
growthman --rename
```

로컬 개발(`pnpm dev`)에서는 `.env` 파일의 `GROWTHMAN_SERVICE_NAME`으로 설정합니다.

```bash
# .env
GROWTHMAN_SERVICE_NAME=growthman-myname
```

다른 기기에서 `dns-sd -B _http._tcp local` 명령으로 서비스를 검색하거나, Bonjour 브라우저 앱으로 확인할 수 있습니다. 서버가 종료되면 서비스 등록이 자동으로 해제됩니다.

## 로그 레벨

`--log-level` 플래그로 프록시 로깅 상세도를 인터랙티브하게 선택할 수 있습니다.

```bash
growthman --log-level
```

```
Log level:
  ❯ info    Request/response summary (default)
    error   Proxy failures only
    warn    + 4xx/5xx responses
    debug   + Response body (pretty-printed)
    trace   + Request headers
```

화살표 키(↑↓)로 이동, Enter로 선택합니다. 로그는 상태코드에 따라 색상이 다르게 출력됩니다 (2xx 초록, 3xx 시안, 4xx 노랑, 5xx 빨강).

환경변수로도 설정할 수 있습니다.

```bash
GROWTHMAN_LOG_LEVEL=debug npx @kurly-growth/growthman
```

| 레벨 | 출력 내용 |
|------|-----------|
| `error` | 프록시 실패(502)만 |
| `warn` | error + 4xx/5xx 응답 |
| `info` (기본값) | 요청/응답 한 줄 요약 (method, url, status, duration) |
| `debug` | info + 응답 바디 (JSON pretty-print) |
| `trace` | debug + 요청 헤더 |

## 로컬 개발

```bash
pnpm install
cp .env.example .env
pnpm db:reset     # DB 스키마 생성 + 시드 데이터
pnpm dev          # http://localhost:3100
```

### 기타 명령어

```bash
pnpm dev          # 개발 서버 실행 (DB 초기화 없이)
pnpm build        # 프로덕션 빌드
pnpm db:reset     # DB 초기화 (마이그레이션 + 시드)
pnpm db:seed      # 시드 데이터만 추가
```

## 배포 (npm publish)

```bash
pnpm release          # patch 버전 업 (0.1.19 → 0.1.20)
pnpm release:minor    # minor 버전 업 (0.1.19 → 0.2.0)
pnpm release:major    # major 버전 업 (0.1.19 → 1.0.0)
```