commit-ai-agent 1.0.8 → 2.0.0

package/.env.example

@@ -1,4 +1,2 @@
 GEMINI_API_KEY=your_gemini_api_key_here
 PORT=3000
-# Optional: 미설정 시 실행 디렉토리(process.cwd())를 자동 사용
-# DEV_ROOT=C:/dev

package/README.md

@@ -2,6 +2,27 @@
 
 AI가 git 커밋과 현재 변경사항을 한국어로 자동 분석해주는 개발자 도구입니다.
 
+---
+
+## CLI AI와 무엇이 다른가요?
+
+Claude Code나 Codex 같은 CLI AI가 있는데 왜 commit-ai-agent를 써야 할까요?
+
+| 기능 | CLI AI (Claude Code / Codex) | commit-ai-agent |
+| ---- | :--------------------------: | :-------------: |
+| 커밋 분석 | 수동 명령어 입력 필요 | **자동** (git commit 직후 백그라운드 실행) |
+| 분석 범위 | 현재 세션 단일 프로젝트 | 현재 프로젝트 자동 분석 |
+| 상시 실행 | 세션 종료 시 중단 | **데몬 서버** — 항상 켜져 있음 |
+| Secret 탐지 | 없음 | **pre-push 훅** — push 전 자격증명 자동 차단 |
+| 오프라인 큐 | 없음 | 서버 꺼진 동안 커밋 → 재시작 시 **자동 처리** |
+| 분석 UI | 터미널 텍스트 | **브라우저 GUI** — 검색·필터·저장 |
+| AI 비용 | 구독료 or API 종량제 | Google Gemini **무료 티어** 지원 |
+| 개인화 | 없음 | 프로젝트별 리포트를 `reports/`에 **자동 저장** |
+
+> commit-ai-agent의 핵심 가치: **"커밋하면 알아서 분석된다"** — 개발자는 코드에만 집중하세요.
+
+---
+
 ## 요구 사항
 
 - [Node.js](https://nodejs.org) 18 이상
@@ -14,7 +35,7 @@ AI가 git 커밋과 현재 변경사항을 한국어로 자동 분석해주는
 
 ### 방법 A — npx (설치 없이 바로 실행)
 
-- 프로젝트가 모여있는 디렉토리 or 프로젝트 루트에서 명령어 실행
+- 프로젝트 루트에서 명령어 실행
 - 해당 디렉토리에서 .env 파일 생성(.env.example 참고)
 
 ```bash
@@ -24,7 +45,7 @@ npx commit-ai-agent
 ### 방법 B — 전역 설치 후 명령어로 실행
 
 - 전역으로 설치하면 어느 위치에서든 `commit-ai-agent` 명령어로 실행 가능
-- 프로젝트가 모여있는 디렉토리 or 프로젝트 루트에서 명령어 실행
+- 프로젝트 루트에서 명령어 실행
 - 해당 디렉토리에서 .env 파일 생성(.env.example 참고)
 
 ```bash
@@ -34,8 +55,6 @@ commit-ai-agent
 
 ### 방법 C — 직접 클론
 
-프로젝트가 모여있는 디렉토리에 클론한 후, 해당 디렉토리에서 명령어 실행
-
 ```bash
 git clone https://github.com/cjy3458/commit-ai-agent.git
 cd commit-ai-agent
@@ -83,13 +102,103 @@ DEV_ROOT=C:/Users/projects => 선택 사항(미설정 시 현재 실행 디렉
 
 ---
 
+## 새 기능 사용법
+
+### Git Hook 자동화 — 커밋 후 자동 분석
+
+서버가 실행 중인 상태에서 git hook을 설치하면, `git commit` 직후 자동으로 분석이 시작됩니다.
+
+> hook은 **현재 디렉토리(CWD)** 프로젝트에만 설치됩니다. hook을 설치할 프로젝트 안에서 명령어를 실행하세요.
+
+#### 1. Hook 설치
+
+```bash
+# 현재 디렉토리 프로젝트에 설치
+commit-ai-agent hook install
+```
+
+#### 2. Hook 상태 확인
+
+```bash
+commit-ai-agent hook status
+```
+
+```
+  훅 설치 상태:
+  ──────────────────────────────────────────────────
+  my-app                   post-commit: ✅  pre-push: ✅
+```
+
+#### 3. Hook 제거
+
+```bash
+commit-ai-agent hook remove
+```
+
+#### 4. 동작 방식
+
+```
+git commit
+   ↓
+post-commit hook 실행
+   ├── 서버가 켜져 있음 → 즉시 분석 시작 (브라우저 UI에서 확인)
+   └── 서버가 꺼져 있음 → 조용히 종료 (분석 생략)
+```
+
+> Hook은 기존 `.git/hooks/post-commit`이 있어도 안전하게 추가됩니다 (기존 내용 유지).
+
+---
+
+### Secret 유출 탐지 — push 전 자동 차단
+
+`pre-push` hook이 설치되어 있으면 `git push` 전에 변경 파일을 자동 스캔합니다.
+실제 자격증명이 감지되면 push가 차단되고 위치와 유형을 알려줍니다.
+
+#### 탐지 패턴
+
+| 유형 | 심각도 |
+| ---- | ------ |
+| AWS Access Key (`AKIA...`) | Critical |
+| Google API Key (`AIza...`) | Critical |
+| GitHub Personal Token (`ghp_...`) | Critical |
+| Slack Token (`xox...`) | Critical |
+| Stripe Secret Key (`sk_live_...`) | Critical |
+| JWT Token | High |
+| Private Key PEM | Critical |
+| 패스워드 직접 할당 | Medium |
+| API Key 직접 할당 | Medium |
+
+#### 차단 메시지 예시
+
+```
+╔══════════════════════════════════════════════════════╗
+║  ⛔  commit-ai-agent: SECRET DETECTED                ║
+╚══════════════════════════════════════════════════════╝
+
+push가 차단됐습니다. 아래 항목을 확인하세요:
+
+  1. 파일: src/config.js:12 [CRITICAL]
+     유형: Google API Key
+     값:   AIza****y8Xw
+```
+
+#### 오탐(false positive)인 경우 우회
+
+```bash
+SKIP_SECRET_SCAN=1 git push
+```
+
+> Gemini API 키가 설정되어 있으면 AI가 오탐 여부를 자동으로 검증하여 불필요한 차단을 줄입니다.
+
+---
+
 ## 문제 해결
 
 **429 오류 (할당량 초과)**
 → Gemini 무료 티어 한도 도달. 잠시 후 재시도하거나 [유료 플랜](https://ai.google.dev)으로 업그레이드하세요.
 
 **프로젝트 목록이 안 뜸**
-→ 기본값은 실행 디렉토리입니다. 필요 시 `DEV_ROOT`를 git 저장소가 모인 상위 폴더로 지정하세요.
+→ 기본값은 실행 디렉토리입니다. `DEV_ROOT` 환경변수로 프로젝트 경로를 직접 지정할 수 있습니다.
 
 **`[DEP0190] DeprecationWarning` 경고 (Node.js 22+)**
 → `shell: true` 옵션과 args 배열을 함께 전달할 때 Node.js 22 이상에서 발생하는 보안 경고입니다. v1.0.7 이상으로 업데이트하면 해결됩니다.
@@ -142,24 +251,31 @@ git checkout -b feat/my-feature
 ## 프로젝트 구조
 
 ```
-commit-analyzer/
+commit-ai-agent/
 ├── bin/
-│   └── cli.js          # CLI 진입점 (npx / npm install -g)
+│   └── cli.js              # CLI 진입점 (npx / npm install -g)
 ├── src/
-│   ├── server.js       # Express 서버 · API 라우트 · SSE 스트리밍
-│   ├── analyzer.js     # Gemini AI 분석 프롬프트 · 재시도 로직
-│   └── git.js          # simple-git 래퍼 (커밋 조회, status diff)
-├── public/             # 프론트엔드 정적 파일 (HTML · CSS · JS)
-├── .env.example        # 환경변수 예시
+│   ├── server.js           # Express 서버 · API 라우트 · SSE 스트리밍
+│   ├── analyzer.js         # Gemini AI 분석 프롬프트 · 재시도 로직
+│   ├── git.js              # simple-git 래퍼 (커밋 조회, status diff)
+│   └── hooks/
+│       ├── installer.js    # git hook 설치·제거·상태 확인
+│       ├── post-commit.js  # post-commit 훅 스크립트 (자동 분석 트리거)
+│       └── pre-push.js     # pre-push 훅 스크립트 (Secret 탐지)
+├── public/                 # 프론트엔드 정적 파일 (HTML · CSS · JS)
+├── .env.example            # 환경변수 예시
 └── package.json
 ```
 
-| 파일              | 역할                                                  |
-| ----------------- | ----------------------------------------------------- |
-| `bin/cli.js`      | npx 실행 시 .env 로드, 브라우저 자동 오픈, 서버 시작  |
-| `src/server.js`   | REST API + SSE 엔드포인트, 리포트 저장                |
-| `src/analyzer.js` | Gemini API 호출, 모델 폴백(2.5→2.0→lite), 지수 백오프 |
-| `src/git.js`      | 프로젝트 목록 탐색, 커밋 diff, working status diff    |
+| 파일                      | 역할                                                          |
+| ------------------------- | ------------------------------------------------------------- |
+| `bin/cli.js`              | npx 실행, hook 서브커맨드 (install / remove / status)         |
+| `src/server.js`           | REST API + SSE 엔드포인트, 리포트 저장                        |
+| `src/analyzer.js`         | Gemini API 호출, 모델 폴백(2.5→2.0→lite), 지수 백오프         |
+| `src/git.js`              | 프로젝트 목록 탐색, 커밋 diff, working status diff            |
+| `src/hooks/installer.js`  | git hook 스크립트 설치·제거 (기존 hook 보존)                  |
+| `src/hooks/post-commit.js`| 커밋 직후 서버 알림 (서버 없으면 조용히 종료)                 |
+| `src/hooks/pre-push.js`   | push 전 15가지 패턴으로 Secret 스캔, Gemini AI 오탐 필터링    |
 
 ---
 

package/bin/cli.js

@@ -2,6 +2,12 @@
 /**
  * commit-ai-agent CLI 진입점
  * npx commit-ai-agent 또는 npm install -g 후 commit-ai-agent 명령으로 실행
+ *
+ * 서브커맨드:
+ *   (없음)           웹 UI 서버 실행
+ *   hook install     현재 디렉토리에 git hook 설치
+ *   hook remove      git hook 제거
+ *   hook status      git hook 설치 상태 확인
  */
 import dotenv from "dotenv";
 import path from "path";
@@ -11,10 +17,100 @@ import { spawn } from "child_process";
 // 사용자 현재 디렉토리의 .env 로드
 dotenv.config({ path: path.resolve(process.cwd(), ".env") });
 
-// 패키지 루트 경로를 환경변수로 전달 (server.js가 public/ 위치를 찾기 위함)
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// 패키지 루트 경로를 환경변수로 전달 (server.js가 public/ 위치를 찾기 위함)
 process.env.COMMIT_ANALYZER_ROOT = path.resolve(__dirname, "..");
 
+const [, , subCmd, ...subArgs] = process.argv;
+
+// ──────────────────────────────────────────────
+//  hook 서브커맨드
+// ──────────────────────────────────────────────
+if (subCmd === "hook") {
+  const action = subArgs[0]; // install | remove | status
+  const { installHooks, removeHooks, getHookStatus } = await import(
+    "../src/hooks/installer.js"
+  );
+
+  function resolveTargets() {
+    return [process.cwd()];
+  }
+
+  if (action === "install") {
+    const targets = await resolveTargets();
+    console.log("");
+    for (const target of targets) {
+      try {
+        const installed = await installHooks(target);
+        console.log(
+          `  ✅ 설치됨: ${path.basename(target)} (${installed.join(", ")})`
+        );
+      } catch (err) {
+        console.error(`  ❌ 실패: ${path.basename(target)} — ${err.message}`);
+      }
+    }
+    console.log("");
+    console.log("  이제 커밋할 때마다 자동으로 분석됩니다.");
+    console.log("  push 전에 secret 유출도 자동으로 검사됩니다.");
+    console.log("");
+    process.exit(0);
+  }
+
+  if (action === "remove") {
+    const targets = await resolveTargets();
+    console.log("");
+    for (const target of targets) {
+      try {
+        const removed = await removeHooks(target);
+        if (removed.length > 0) {
+          console.log(
+            `  ✅ 제거됨: ${path.basename(target)} (${removed.join(", ")})`
+          );
+        } else {
+          console.log(`  ℹ️  훅 없음: ${path.basename(target)}`);
+        }
+      } catch (err) {
+        console.error(`  ❌ 실패: ${path.basename(target)} — ${err.message}`);
+      }
+    }
+    console.log("");
+    process.exit(0);
+  }
+
+  if (action === "status") {
+    const targets = await resolveTargets();
+    console.log("");
+    console.log("  훅 설치 상태:");
+    console.log("  " + "─".repeat(50));
+    for (const target of targets) {
+      try {
+        const status = await getHookStatus(target);
+        const pc = status.postCommit.installed ? "✅" : "❌";
+        const pp = status.prePush.installed ? "✅" : "❌";
+        console.log(
+          `  ${path.basename(target).padEnd(24)} post-commit: ${pc}  pre-push: ${pp}`
+        );
+      } catch (err) {
+        console.error(`  ❌ 오류: ${path.basename(target)} — ${err.message}`);
+      }
+    }
+    console.log("");
+    process.exit(0);
+  }
+
+  // 알 수 없는 action
+  console.log("");
+  console.log("  사용법:");
+  console.log("    commit-ai-agent hook install   # 현재 디렉토리에 훅 설치");
+  console.log("    commit-ai-agent hook remove    # 훅 제거");
+  console.log("    commit-ai-agent hook status    # 상태 확인");
+  console.log("");
+  process.exit(1);
+}
+
+// ──────────────────────────────────────────────
+//  기본 동작: 웹 UI 서버 실행
+// ──────────────────────────────────────────────
 const PORT = process.env.PORT || 3000;
 
 console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commit-ai-agent",
-  "version": "1.0.8",
+  "version": "2.0.0",
   "description": "AI-powered git commit & working status analyzer with web UI",
   "type": "module",
   "main": "src/server.js",