# WhaTap MXQL CLI

WhaTap 모니터링 데이터를 MXQL(Metrics Query Language)로 조회하는 명령줄 인터페이스입니다.

## ✨ 기능

- 🔐 **안전한 인증**: AES-256-GCM 암호화된 세션 저장
- 📊 **프로젝트 관리**: 접근 가능한 모든 프로젝트 조회 및 필터링
- 🔍 **MXQL 쿼리**: 강력한 MXQL 쿼리 실행 (복잡한 파이프라인 지원)
- 🎨 **다양한 출력 형식**: Table, JSON, CSV
- 💬 **대화형 REPL**: 인터랙티브한 쿼리 실행 환경
- ⏰ **시간 범위 지원**: 프리셋 및 커스텀 시간 범위
- 🚀 **MCP 서버**: Claude Code 통합 완료! (Tools 제공)
- 🤖 **Skill 통합**: mxql-for-claude-code Skill과 함께 사용 (자연어 → MXQL)

## 🚀 빠른 시작

### 설치

```bash
# 저장소 클론
git clone <repository-url>
cd whatap-mxql-cli

# 의존성 설치
npm install

# 빌드
npm run build

# bin 실행 권한 부여
chmod +x bin/whatap-mxql
```

### 기본 사용법

```bash
# 방법 1: 명령어 바로 실행 (자동 로그인 유도)
./bin/whatap-mxql projects
# → 로그인 안 되어 있으면 자동으로 로그인 프롬프트 표시

# 방법 2: 명시적 로그인 후 사용
./bin/whatap-mxql login
./bin/whatap-mxql projects

# 3. MXQL 쿼리 실행
./bin/whatap-mxql query 27506 "CATEGORY app_counter" -r 24h

# 4. 대화형 모드
./bin/whatap-mxql interactive
```

**💡 TIP**: 로그인 없이 어떤 명령어든 실행하면 자동으로 로그인 프롬프트가 표시됩니다!

## 📋 명령어

| 명령어 | 설명 |
|--------|------|
| `login [options]` | WhaTap 서비스 로그인 |
| `logout` | 로그아웃 및 세션 삭제 |
| `projects [options]` | 프로젝트 목록 조회 |
| `query <pcode> [mxql] [options]` | MXQL 쿼리 실행 |
| `interactive [options]` | 대화형 REPL 모드 |

상세 사용법은 [CLI_GUIDE.md](./CLI_GUIDE.md)를 참조하세요.

## 🤖 Claude Code 통합 (MCP)

### MCP 서버 설정

```bash
# 빌드 (이미 완료된 경우 skip)
npm run build

# MCP 설정 파일 생성
mkdir -p ~/.claude/mcp
cat > ~/.claude/mcp/whatap-mxql.json << 'EOF'
{
  "mcpServers": {
    "whatap-mxql": {
      "command": "node",
      "args": ["/절대/경로/whatap-mxql-cli/dist/mcp/index.js"],
      "description": "WhaTap MXQL Query Executor"
    }
  }
}
EOF
```

⚠️ **중요**: `/절대/경로/`를 실제 프로젝트 경로로 변경하세요!

### Skill 설치 (mxql-for-claude-code)

```bash
# 저장소 클론
git clone https://github.com/kyupid/mxql-for-claude-code.git
cd mxql-for-claude-code

# 설치
./install.sh
```

### 사용 예시

```
사용자: "PostgreSQL에서 CPU 80% 이상인 인스턴스 찾아줘"

Claude Code:
  1. (Skill) PostgreSQL 카테고리 및 MXQL 패턴 학습
  2. (Skill) MXQL 생성: "CATEGORY db_postgresql_counter FILTER..."
  3. (MCP Tool) whatap.getProjects() - 프로젝트 목록 확인
  4. (MCP Tool) whatap.executeMxql(pcode, mxql) - 쿼리 실행
  5. 결과 분석 및 응답
```

상세 설치 가이드: [MCP_INSTALLATION.md](./MCP_INSTALLATION.md)

## 🎨 출력 예시

### 프로젝트 목록
```
✓ Found 12 project(s)

┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ Project Code │ Project Name            │ Type    │ Status     │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 27506        │ Browser Monitoring Demo │ BROWSER │ subscribe  │
│ 44482        │ mobile test project     │ MOBILE  │ subscribe  │
└──────────────┴─────────────────────────┴─────────┴────────────┘
```

### MXQL 쿼리 결과
```json
[
  {
    "_id_": "27506_",
    "pname": "Browser Monitoring Demo",
    "pcode": 27506,
    "sessionCount": 108.04790419161677,
    "_rows_": 167
  }
]
```

## 🔧 Development

### Setup

```bash
npm install
```

### Build

```bash
npm run build
```

### Test

```bash
# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests (requires WhaTap account)
npm run test:integration

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage
```

### Lint & Format

```bash
npm run lint
npm run lint:fix
npm run format
```

## 🧪 Testing

### Unit Tests

Mock-based tests for all modules without external dependencies.

### Integration Tests

Real API calls to WhaTap service (requires test account).

Configure test credentials in `.env.test`:

```bash
WHATAP_TEST_EMAIL=your-email@whatap.io
WHATAP_TEST_PASSWORD=your-password
WHATAP_SERVICE_URL=https://service.whatap.io
RUN_INTEGRATION_TESTS=true
```

## 📁 프로젝트 구조

```
whatap-mxql-cli/
├── src/
│   ├── core/                 # 핵심 모듈 (CLI & MCP 공유)
│   │   ├── types/           # TypeScript 타입 정의
│   │   ├── auth/            # 인증 모듈
│   │   │   ├── SessionStore.ts      # 세션 저장 (AES-256-GCM)
│   │   │   └── AuthManager.ts       # 인증 관리 (Cookie Jar)
│   │   ├── client/          # API 클라이언트
│   │   │   └── WhatapClient.ts      # WhaTap API (Dual Auth)
│   │   └── executor/        # MXQL 실행기
│   │       └── MxqlExecutor.ts      # 쿼리 실행 및 편의 메서드
│   └── cli/                  # CLI 인터페이스
│       ├── commands/        # 명령어 구현
│       │   ├── login.ts
│       │   ├── logout.ts
│       │   ├── projects.ts
│       │   ├── query.ts
│       │   └── interactive.ts
│       ├── utils/           # 유틸리티
│       │   ├── formatters.ts        # 출력 포맷팅
│       │   └── session.ts           # 세션 관리
│       └── index.ts         # CLI 진입점
├── test/                     # 테스트
├── bin/                      # 실행 파일
│   └── whatap-mxql
└── dist/                     # 빌드 출력
```

## 📊 테스트 현황

### Core 모듈 (52개 유닛 테스트)
- ✅ SessionStore: 16/16 테스트 통과
- ✅ AuthManager: 16/16 테스트 통과
- ✅ WhatapClient: 13/13 테스트 통과
- ✅ MxqlExecutor: 7/7 테스트 통과

### CLI
- ✅ login: 정상 동작
- ✅ logout: 정상 동작
- ✅ projects: 정상 동작 (12개 프로젝트 조회)
- ✅ query: 정상 동작 (실제 데이터 조회 성공)
- ✅ interactive: 정상 동작
- ✅ 출력 형식: Table, JSON, CSV 모두 정상

### 실제 데이터 조회
- ✅ 복잡한 MXQL 파이프라인 쿼리 실행
- ✅ 프로젝트 27506에서 sessionCount 데이터 조회
- ✅ 167개 행 집계 결과 반환
- ✅ 바이너리 데이터 포함한 복잡한 구조 처리

상세 검증 결과는 [VERIFICATION_REPORT.md](./VERIFICATION_REPORT.md)를 참조하세요.

## 📝 License

MIT

## 🔒 Security

Session data is encrypted using AES-256-GCM. Encryption keys are stored locally with restricted permissions (0600).

Never commit `.env.test` or any files containing credentials to version control.