@blum84/smart-commit 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +240 -29
  2. package/dist/chunk-LYR3U55E.js +496 -0
  3. package/dist/chunk-LYR3U55E.js.map +1 -0
  4. package/dist/{chunk-ZS27WQDW.js → chunk-MYMEBX2Q.js} +27 -3
  5. package/dist/chunk-MYMEBX2Q.js.map +1 -0
  6. package/dist/{classifier-TTZQUM7N.js → classifier-AINQPFLU.js} +4 -2
  7. package/dist/index.js +36 -459
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp-server.js +239 -0
  10. package/dist/mcp-server.js.map +1 -0
  11. package/package.json +8 -4
  12. package/dist/chunk-ZS27WQDW.js.map +0 -1
  13. /package/dist/{classifier-TTZQUM7N.js.map → classifier-AINQPFLU.js.map} +0 -0
package/README.md CHANGED
@@ -1,94 +1,305 @@
1
- # smart-commit
1
+ # @blum84/smart-commit
2
2
 
3
3
  AI 기반 지능형 Git 자동 커밋 & 푸시 CLI 도구
4
4
 
5
- 현재 디렉토리 하위의 모든 Git 저장소를 스캔하여, AI(Gemini/Claude)로 커밋 메시지를 자동 생성하고, 안전하게 커밋/푸시합니다.
5
+ 현재 디렉토리 하위의 모든 Git 저장소를 스캔하여, AI(Gemini/Claude/GPT/Ollama)로 커밋 메시지를 자동 생성하고, 안전하게 커밋/푸시합니다.
6
6
 
7
7
  ## 설치 & 실행
8
8
 
9
9
  ```bash
10
10
  # 설치 없이 바로 실행
11
- npx smart-commit
11
+ npx @blum84/smart-commit
12
12
 
13
13
  # 글로벌 설치
14
- npm install -g smart-commit
14
+ npm install -g @blum84/smart-commit
15
15
  smart-commit
16
16
  ```
17
17
 
18
+ ## 사전 요구사항
19
+
20
+ - **Node.js** >= 18
21
+ - 다음 중 하나 이상의 AI CLI 도구:
22
+
23
+ | AI 도구 | 설치 방법 |
24
+ |---------|----------|
25
+ | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` |
26
+ | [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) | Anthropic 공식 CLI |
27
+ | [OpenAI CLI](https://platform.openai.com/docs/guides/command-line) | `pip install openai` |
28
+ | [Ollama](https://ollama.com/) | `brew install ollama` |
29
+
30
+ AI 도구가 없으면 자동으로 오프라인 모드(템플릿 선택)로 전환됩니다.
31
+
18
32
  ## 주요 기능
19
33
 
20
- - **AI 커밋 메시지 생성** — Gemini/Claude CLI로 diff 분석 후 한국어 커밋 메시지 자동 생성
21
- - **안전 필터** — `.env`, `.pem`, 대용량 파일 자동 차단, 위험 파일 경고
34
+ - **AI 커밋 메시지 생성** — diff 분석 후 Conventional Commits 형식의 한국어 메시지 자동 생성
35
+ - **AI 파일 그룹핑** — 관련 파일을 의미 단위로 묶어 커밋 분리
36
+ - **안전 필터** — `.env`, `.pem`, 대용량 파일 자동 차단 + 글로벌 `.gitignore` 반영
22
37
  - **Git 상태 감지** — Detached HEAD, Rebase/Merge 진행 중, Lock 파일 등 비정상 상태 안전 스킵
23
38
  - **AI Fallback** — 주 AI 도구 실패 시 대체 도구로 자동 전환
39
+ - **Conventional Commits 검증** — 생성된 메시지가 형식에 맞지 않으면 AI에게 재생성 요청
40
+ - **지능적 Diff 요약** — 대용량 diff를 stat + 핵심 hunk로 압축하여 AI에 전달
41
+ - **AI 충돌 해결** — 충돌 마커 단위로 블록별 정밀 해결 + 사용자 최종 확인
24
42
  - **Dry-run 모드** — 실제 커밋/푸시 없이 미리보기
43
+ - **오프라인 모드** — AI 미접속 시 로컬 커밋 템플릿 선택
44
+ - **Headless/CI 모드** — 비대화형 환경에서 자동 커밋/푸시
45
+ - **Git Hook** — prepare-commit-msg / post-commit 훅 설치/제거
46
+ - **MCP 서버** — Claude Code 등에서 MCP 도구로 사용 가능
25
47
  - **TUI** — terminal-kit 기반 프로그레스바, 테이블, 메뉴 선택
26
48
 
27
- ## 사전 요구사항
28
-
29
- 다음 중 하나 이상의 AI CLI 도구가 설치되어 있어야 합니다:
30
-
31
- - [Gemini CLI](https://github.com/google-gemini/gemini-cli) — `npm install -g @google/gemini-cli`
32
- - [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) — Anthropic 공식 CLI
33
-
34
49
  ## 사용법
35
50
 
36
51
  ```bash
37
52
  # 기본 실행 (하위 모든 Git 저장소 스캔)
38
53
  smart-commit
39
54
 
40
- # Dry-run (미리보기만)
55
+ # Dry-run (미리보기만, 실제 커밋 없음)
41
56
  smart-commit --dry-run
42
57
 
43
58
  # AI 도구 지정
44
59
  smart-commit --ai claude
60
+ smart-commit --ai gpt
61
+ smart-commit --ai ollama
45
62
 
46
- # 그룹핑 전략 지정
47
- smart-commit --group single # 모든 변경을 하나의 커밋으로
63
+ # 그룹핑 전략
48
64
  smart-commit --group smart # AI가 의미 단위로 그룹핑 (기본값)
65
+ smart-commit --group single # 모든 변경을 하나의 커밋으로
66
+ smart-commit --group manual # 파일별 선택
49
67
 
50
- # 비대화형 모드
68
+ # 비대화형 모드 (CI/자동화용)
51
69
  smart-commit --no-interactive
70
+
71
+ # 오프라인 모드 (AI 없이 템플릿 사용)
72
+ smart-commit --offline
73
+
74
+ # Git Hook 설치/제거
75
+ smart-commit hook
76
+ smart-commit hook --uninstall
77
+ ```
78
+
79
+ ### 대화형 메뉴
80
+
81
+ 각 저장소/그룹마다 다음 액션을 선택할 수 있습니다:
82
+
83
+ | 액션 | 설명 |
84
+ |------|------|
85
+ | **Push** | 커밋 + 원격 푸시 |
86
+ | **Skip** | 로컬 커밋만 유지 |
87
+ | **Cancel** | 이 그룹 커밋 안 함 |
88
+ | **Skip repo** | 현재 저장소 전체 건너뛰기 |
89
+ | **Exit** | 즉시 종료 |
90
+
91
+ ## 커밋 메시지 규칙
92
+
93
+ smart-commit은 [Conventional Commits](https://www.conventionalcommits.org/) + [커밋 메시지 가이드](https://github.com/RomuloOliveira/commit-messages-guide/blob/master/README_ko-KR.md) 표준을 따릅니다. AI가 자동으로 이 형식에 맞춰 메시지를 생성하고, 검증 후 재생성합니다.
94
+
95
+ ### 구조
96
+
97
+ ```
98
+ <type>(<scope>): <subject>
99
+
100
+ <body>
101
+
102
+ <footer>
103
+ ```
104
+
105
+ | 구분 | 규칙 | 예시 |
106
+ |------|------|------|
107
+ | **type** | 변경 유형 (필수) | `feat`, `fix`, `refactor` |
108
+ | **scope** | 영향 범위 (선택) | `auth`, `api`, `ui` |
109
+ | **subject** | 50자 이내, 명령조, 핵심 요약 (필수) | `사용자 로그인 API 구현` |
110
+ | **body** | 72자/줄, "왜" 변경했는지 설명 (선택) | 상세 변경 내용 bullet 목록 |
111
+ | **footer** | 이슈 참조, Breaking Change (선택) | `Closes #123` |
112
+
113
+ ### Type 종류
114
+
115
+ | Type | 설명 | 예시 |
116
+ |------|------|------|
117
+ | `feat` | 새로운 기능 추가 | `feat(auth): 소셜 로그인 구현` |
118
+ | `fix` | 버그 수정 | `fix(api): 토큰 만료 시 500 에러 수정` |
119
+ | `refactor` | 기능 변경 없는 코드 개선 | `refactor: 인증 미들웨어 구조 개선` |
120
+ | `docs` | 문서 변경 | `docs: API 엔드포인트 설명 추가` |
121
+ | `style` | 포맷팅, 세미콜론 등 | `style: 들여쓰기 2칸으로 통일` |
122
+ | `test` | 테스트 추가/수정 | `test(auth): 로그인 실패 케이스 추가` |
123
+ | `chore` | 빌드, 설정, 의존성 | `chore: typescript 5.8로 업그레이드` |
124
+ | `perf` | 성능 개선 | `perf(query): N+1 쿼리 제거` |
125
+ | `ci` | CI/CD 설정 | `ci: GitHub Actions 캐시 설정` |
126
+ | `build` | 빌드 시스템 | `build: webpack → vite 전환` |
127
+ | `revert` | 이전 커밋 되돌림 | `revert: feat(auth) 소셜 로그인 롤백` |
128
+
129
+ ### 좋은 예시 vs 나쁜 예시
130
+
131
+ ```
132
+ # 좋은 예시 ✅
133
+ feat(auth): JWT 기반 인증 미들웨어 구현
134
+
135
+ - Access/Refresh 토큰 발급 로직 추가
136
+ - 토큰 만료 시 자동 갱신 처리
137
+ - 인증 실패 시 401 응답 통일
138
+
139
+ Closes #42
140
+
141
+ # 나쁜 예시 ❌
142
+ 수정함 # type 없음, 무엇을 수정했는지 불명
143
+ fix: 버그 수정 # 어떤 버그인지 불명
144
+ feat: 여러가지 수정 및 기능 추가 # 하나의 커밋에 여러 변경 혼합
145
+ FEAT: 로그인 추가 # 대문자 type
52
146
  ```
53
147
 
148
+ ### 작성 원칙
149
+
150
+ 1. **제목은 "무엇을"**, 본문은 **"왜"** 에 집중
151
+ 2. **명령조** 사용 — "추가", "수정", "제거" (O) / "추가함", "수정했음" (X)
152
+ 3. **하나의 커밋 = 하나의 논리적 변경** — 관련 없는 변경은 분리
153
+ 4. **제목 50자, 본문 72자/줄** 제한 준수
154
+ 5. **부수 효과**가 있으면 본문에 명시
155
+
156
+ > smart-commit의 `--group smart` 옵션은 AI가 관련 파일을 의미 단위로 자동 그룹핑하여 "하나의 커밋 = 하나의 논리적 변경" 원칙을 지킵니다.
157
+
54
158
  ## 설정
55
159
 
56
- 프로젝트 루트 또는 홈 디렉토리에 `.smart-commitrc.yaml` 파일을 생성하세요:
160
+ 프로젝트 루트 또는 홈 디렉토리에 `.smart-commitrc.yaml` 파일을 생성하세요. [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig)을 사용하므로 다음 파일명도 지원합니다: `.smart-commitrc`, `.smart-commitrc.json`, `smart-commit.config.js`
57
161
 
58
162
  ```yaml
59
163
  ai:
60
- primary: gemini
61
- fallback: claude
62
- timeout: 30
164
+ primary: gemini # 기본 AI: gemini | claude | gpt | ollama
165
+ fallback: claude # 실패 시 대체 AI
166
+ timeout: 30 # AI 응답 타임아웃 (초)
167
+ ollama: # Ollama 사용 시 설정
168
+ model: llama3
169
+ host: http://localhost:11434
63
170
 
64
171
  safety:
65
- maxFileSize: 10MB
66
- blockedPatterns:
172
+ maxFileSize: 10MB # 이 이상은 자동 차단
173
+ blockedPatterns: # 절대 커밋 금지
67
174
  - "*.env"
175
+ - ".env.*"
68
176
  - "*.pem"
69
177
  - "*.key"
70
178
  - "credentials*"
71
- warnPatterns:
179
+ - "*.sqlite"
180
+ warnPatterns: # 경고 후 사용자 확인
72
181
  - "*.log"
182
+ - "*.csv"
73
183
  - "package-lock.json"
184
+ - "yarn.lock"
74
185
 
75
186
  commit:
76
- style: conventional
77
- language: ko
78
- maxDiffSize: 10000
187
+ style: conventional # conventional | free
188
+ language: ko # 커밋 메시지 언어 (ko | en)
189
+ maxDiffSize: 10000 # AI에 보낼 diff 최대 문자 수
79
190
 
80
191
  grouping:
81
- strategy: smart
192
+ strategy: smart # smart | single | manual
82
193
  ```
83
194
 
195
+ 설정 없이도 기본값으로 동작합니다. 글로벌 `.gitignore` 패턴도 자동으로 차단 목록에 반영됩니다.
196
+
84
197
  ## 안전 필터
85
198
 
86
199
  | 분류 | 동작 | 패턴 예시 |
87
200
  |------|------|----------|
88
- | **차단** | 커밋에서 자동 제외 | `.env`, `.pem`, `.key`, `credentials*`, 10MB 초과 |
201
+ | **차단** | 커밋에서 자동 제외 | `.env`, `.pem`, `.key`, `credentials*`, 10MB 초과, 바이너리, 글로벌 gitignore 패턴 |
89
202
  | **경고** | 사용자 확인 후 포함 | `.log`, `.csv`, `package-lock.json` |
90
203
  | **안전** | 정상 커밋 | 그 외 모든 파일 |
91
204
 
205
+ ## Git 상태 예외 처리
206
+
207
+ | 상태 | 대응 |
208
+ |------|------|
209
+ | Detached HEAD | 경고 출력 후 스킵 |
210
+ | Rebase 진행 중 | "rebase 완료 후 재시도" 안내, 스킵 |
211
+ | Merge 진행 중 | 충돌 해결 플로우로 분기 |
212
+ | Git Hook 실패 | 에러 표시 + retry/skip 선택 |
213
+ | Lock 파일 존재 | "다른 Git 프로세스 실행 중" 안내, 스킵 |
214
+
215
+ ## MCP 서버
216
+
217
+ Claude Code 등에서 MCP 도구로 사용할 수 있습니다.
218
+
219
+ ```json
220
+ // .mcp.json
221
+ {
222
+ "smart-commit": {
223
+ "command": "node",
224
+ "args": ["/path/to/smart-commit/dist/mcp-server.js"]
225
+ }
226
+ }
227
+ ```
228
+
229
+ ### MCP 도구 목록
230
+
231
+ | Tool | 설명 |
232
+ |------|------|
233
+ | `scan` | 하위 Git 저장소 스캔 — 변경 상태 확인 |
234
+ | `analyze` | 변경 파일 분석 + 안전 필터 적용 |
235
+ | `generate-message` | AI로 diff 기반 커밋 메시지 생성 |
236
+ | `commit` | 커밋 실행 (AI 메시지 자동 생성 또는 직접 지정, push 옵션) |
237
+ | `config` | 현재 설정 확인 |
238
+
239
+ ## 의존성
240
+
241
+ ### Runtime
242
+
243
+ | 패키지 | 용도 |
244
+ |--------|------|
245
+ | [commander](https://github.com/tj/commander.js) | CLI 파서 |
246
+ | [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) | 설정 파일 자동 탐색 |
247
+ | [simple-git](https://github.com/steveukx/git-js) | Git 연동 |
248
+ | [execa](https://github.com/sindresorhus/execa) | AI CLI 서브프로세스 호출 |
249
+ | [terminal-kit](https://github.com/cronvel/terminal-kit) | TUI (프로그레스바, 테이블, 메뉴) |
250
+ | [minimatch](https://github.com/isaacs/minimatch) | glob 패턴 매칭 (안전 필터) |
251
+ | [pino](https://github.com/pinojs/pino) | 구조화 로깅 |
252
+ | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) | MCP 서버 |
253
+ | [zod](https://github.com/colinhacks/zod) | MCP 파라미터 검증 |
254
+
255
+ ### DevDependencies
256
+
257
+ | 패키지 | 용도 |
258
+ |--------|------|
259
+ | [typescript](https://www.typescriptlang.org/) | 타입 안전성 |
260
+ | [tsup](https://github.com/egoist/tsup) | 빌드/번들링 |
261
+ | [vitest](https://vitest.dev/) | 테스트 |
262
+
263
+ ## 개발
264
+
265
+ ```bash
266
+ # 의존성 설치
267
+ npm install
268
+
269
+ # 개발 모드 (watch)
270
+ npm run dev
271
+
272
+ # 빌드
273
+ npm run build
274
+
275
+ # 타입 체크
276
+ npm run lint
277
+
278
+ # 테스트
279
+ npm test
280
+
281
+ # 테스트 (CI용, 단일 실행)
282
+ npm run test:run
283
+ ```
284
+
285
+ ## 프로젝트 구조
286
+
287
+ ```
288
+ src/
289
+ ├── index.ts CLI 엔트리포인트
290
+ ├── mcp-server.ts MCP 서버
291
+ ├── config.ts 설정 로딩 (cosmiconfig)
292
+ ├── scanner.ts 저장소 탐색 + Git 상태 예외 처리
293
+ ├── classifier.ts 안전 필터 + AI/규칙 기반 그룹핑
294
+ ├── ai-client.ts AI 호출 (Gemini/Claude/GPT/Ollama) + 검증
295
+ ├── committer.ts 커밋/푸시 + pull 재시도
296
+ ├── conflict-resolver.ts 충돌 마커 단위 AI 해결
297
+ ├── ui.ts terminal-kit TUI
298
+ ├── logger.ts pino 로깅
299
+ ├── types.ts 타입 정의
300
+ └── hooks/install.ts Git Hook 설치/제거
301
+ ```
302
+
92
303
  ## License
93
304
 
94
305
  MIT