@purpleraven/hits 0.2.0

package/data/dev_handover.yaml

@@ -0,0 +1,143 @@
+# HITS 프로젝트 지식 트리 샘플
+# 이 파일은 HITS 지식 트리 구조의 예시입니다.
+
+tree:
+  id: hits-knowledge-001
+  name: "HITS 프로젝트 핵심 지식"
+  description: "HITS 시스템 개발에 필요한 핵심 지식 트리"
+  
+  nodes:
+    # WHY Layer - 의도/목적
+    - id: why-architecture
+      layer: why
+      title: "시스템 아키텍처 이해"
+      description: |
+        HITS는 hits_core(순수 Python) + hits_ui(PySide6) 구조
+        → 목적: AI 토큰 최적화 + 지식 보존
+        → 격리: core는 GUI 의존성 없음
+        → 저장: ~/.hits/data/에 중앙 집중
+      tokens_saved: 50
+      
+    - id: why-handover
+      layer: why
+      title: "AI 세션 인수인계"
+      description: |
+        토큰 한계 등으로 AI 교체 시 프로젝트 컨텍스트 유지
+        → 프로젝트별 project_path로 격리
+        → 세션 종료 시 작업 기록, 시작 시 요약 조회
+      tokens_saved: 40
+      
+    # HOW Layer - 논리/방법
+    - id: how-storage
+      layer: how
+      title: "중앙 집중 저장소"
+      parent_id: why-architecture
+      description: |
+        FileStorage 기본 경로: ~/.hits/data/
+        → work_logs/: 작업 기록 JSON
+        → trees/: 지식 트리
+        → HITS_DATA_PATH 환경변수로 오버라이드
+      tokens_saved: 35
+      
+    - id: how-mcp
+      layer: how
+      title: "MCP 인터페이스"
+      parent_id: why-handover
+      description: |
+        hits_core/mcp/server.py가 MCP 서버 제공
+        → 5개 툴: record_work, get_handover, search_works, list_projects, get_recent
+        → stdio transport로 Claude/OpenCode와 직접 통신
+      tokens_saved: 30
+      
+    - id: how-api
+      layer: how
+      title: "HTTP API 서버"
+      parent_id: why-handover
+      description: |
+        FastAPI 기반, 포트 8765
+        → /api/handover: 인수인계 요약
+        → /api/work-log: 작업 기록 CRUD
+        → /api/work-logs/search: 검색 (project_path 스코프)
+      tokens_saved: 30
+      
+    - id: how-compression
+      layer: how
+      title: "시멘틱 압축"
+      parent_id: why-architecture
+      description: |
+        SemanticCompressor가 한국어 키워드를 기호로 치환
+        → "따라서" → "→", "중요" → "★", "필수" → "!"
+        → SLMFilter가 CRITICAL/IMPORTANT/NOISE 분류
+      node_type: "negative_path"
+      tokens_saved: 25
+      
+    # WHAT Layer - 실행/작업
+    - id: what-run
+      layer: what
+      title: "실행 방법"
+      parent_id: how-storage
+      description: |
+        ./run.sh          # GUI 실행
+        ./run.sh --check  # pre-flight 체크
+        ./run.sh --test   # 테스트 실행
+      action: "bash ./run.sh"
+      action_type: shell
+      tokens_saved: 15
+      
+    - id: what-record
+      layer: what
+      title: "작업 기록"
+      parent_id: how-api
+      description: |
+        curl -X POST http://localhost:8765/api/work-log \
+          -d '{"performed_by":"opencode","request_text":"요약","source":"ai_session","project_path":"/절대경로"}'
+      action: "curl -X POST http://localhost:8765/api/work-log"
+      action_type: shell
+      tokens_saved: 20
+      
+    - id: what-handover
+      layer: what
+      title: "인수인계 조회"
+      parent_id: how-api
+      description: |
+        curl http://localhost:8765/api/handover?project_path=/my/project
+        → 프로젝트별 작업 이력, 결정 사항, 미완료 항목 반환
+      action: "curl http://localhost:8765/api/handover?project_path=$(pwd)"
+      action_type: shell
+      tokens_saved: 20
+
+# 인과관계 워크플로우
+workflow:
+  id: ai-session-handover
+  name: "AI 세션 인수인계 워크플로우"
+  description: "AI 세션 전환 시 표준 인수인계 절차"
+  
+  steps:
+    - id: step-start
+      name: "세션 시작"
+      step_type: trigger
+      node_id: why-handover
+      next_steps: ["step-check-handover"]
+      
+    - id: step-check-handover
+      name: "이전 작업 확인"
+      step_type: action
+      node_id: what-handover
+      next_steps: ["step-work"]
+      
+    - id: step-work
+      name: "작업 수행"
+      step_type: action
+      node_id: what-run
+      next_steps: ["step-record"]
+      
+    - id: step-record
+      name: "작업 기록"
+      step_type: action
+      node_id: what-record
+      next_steps: ["step-end"]
+      
+    - id: step-end
+      name: "세션 종료"
+      step_type: outcome
+      node_id: why-handover

package/hits_core/__init__.py

@@ -0,0 +1,9 @@
+"""
+HITS Core - Hybrid Intel Trace System Core Library
+
+Apache 2.0 License
+Pure Python implementation without GUI dependencies.
+"""
+
+__version__ = "0.1.0"
+__license__ = "Apache-2.0"

package/hits_core/ai/__init__.py

@@ -0,0 +1,11 @@
+"""AI module for token optimization and knowledge compression."""
+
+from .compressor import SemanticCompressor
+from .slm_filter import SLMFilter
+from .llm_client import LLMClient
+
+__all__ = [
+    "SemanticCompressor",
+    "SLMFilter",
+    "LLMClient",
+]

package/hits_core/ai/compressor.py

@@ -0,0 +1,86 @@
+"""Semantic compression for token-efficient knowledge storage."""
+
+from typing import Optional
+from ..models.node import Node
+
+
+class SemanticCompressor:
+    KEYWORD_MAP = {
+        "따라서": "→",
+        "그래서": "→",
+        "그러므로": "→",
+        "그러나": "↔",
+        "하지만": "↔",
+        "또한": "+",
+        "그리고": "+",
+        "또는": "|",
+        "만약": "?",
+        "만일": "?",
+        "그러면": "→",
+        "결과": "⊕",
+        "원인": "⊙",
+        "목적": "◎",
+        "방법": "⚙",
+        "주의": "⚠",
+        "중요": "★",
+        "필수": "!",
+        "선택": "○",
+        "성공": "✓",
+        "실패": "✗",
+        "버그": "🐛",
+        "수정": "🔧",
+        "배포": "🚀",
+        "테스트": "🧪",
+    }
+    
+    COMPRESSION_RULES = [
+        ("입니다", ""),
+        ("있습니다", "+"),
+        ("없습니다", "-"),
+        ("합니다", "."),
+        ("되어야 합니다", "→!"),
+        ("해야 합니다", "→!"),
+        ("필요합니다", "!"),
+        ("가능합니다", "✓"),
+        ("불가능합니다", "✗"),
+        ("중요합니다", "★!"),
+        ("필수입니다", "!"),
+    ]
+    
+    def compress(self, text: str) -> str:
+        if not text:
+            return text
+        
+        result = text
+        
+        for keyword, symbol in self.KEYWORD_MAP.items():
+            result = result.replace(keyword, f" {symbol} ")
+        
+        for full, compressed in self.COMPRESSION_RULES:
+            result = result.replace(full, compressed)
+        
+        while "  " in result:
+            result = result.replace("  ", " ")
+        
+        return result.strip()
+    
+    def compress_node(self, node: Node) -> int:
+        original_length = len(node.description or "")
+        
+        if node.description:
+            node.description = self.compress(node.description)
+        
+        for key, value in node.metadata.items():
+            if isinstance(value, str):
+                node.metadata[key] = self.compress(value)
+        
+        compressed_length = len(node.description or "")
+        tokens_saved = max(0, (original_length - compressed_length) // 4)
+        
+        node.tokens_saved = tokens_saved
+        return tokens_saved
+    
+    def estimate_tokens(self, text: str) -> int:
+        korean_chars = sum(1 for c in text if '\uAC00' <= c <= '\uD7A3')
+        other_chars = len(text) - korean_chars
+        return (korean_chars // 2) + (other_chars // 4)

package/hits_core/ai/llm_client.py

@@ -0,0 +1,65 @@
+"""LLM client for on-demand knowledge analysis."""
+
+from typing import Optional
+from abc import ABC, abstractmethod
+
+
+class LLMProvider(ABC):
+    @abstractmethod
+    async def generate(self, prompt: str, max_tokens: int = 1000) -> str:
+        pass
+
+
+class MockLLMProvider(LLMProvider):
+    async def generate(self, prompt: str, max_tokens: int = 1000) -> str:
+        return f"[Mock Response] Analyzed: {prompt[:50]}..."
+
+
+class LLMClient:
+    def __init__(self, provider: Optional[LLMProvider] = None):
+        self.provider = provider or MockLLMProvider()
+        self.total_tokens_used = 0
+    
+    async def analyze_node(self, node_data: str, max_tokens: int = 500) -> str:
+        prompt = f"""다음 지식 노드를 분석하여 핵심 맥락을 요약하세요:
+
+{node_data}
+
+요약:"""
+        
+        response = await self.provider.generate(prompt, max_tokens)
+        self.total_tokens_used += max_tokens
+        return response
+    
+    async def suggest_children(self, node_data: str, max_tokens: int = 300) -> list[str]:
+        prompt = f"""다음 지식 노드에 대해 적절한 하위 항목을 3-5개 제안하세요:
+
+{node_data}
+
+하위 항목:"""
+        
+        response = await self.provider.generate(prompt, max_tokens)
+        self.total_tokens_used += max_tokens
+        
+        suggestions = [
+            line.strip().lstrip("0123456789.-) ")
+            for line in response.split("\n")
+            if line.strip()
+        ]
+        return suggestions[:5]
+    
+    async def generate_handover_summary(
+        self,
+        tree_data: str,
+        max_tokens: int = 1000
+    ) -> str:
+        prompt = f"""다음 지식 트리를 기반으로 인수인계 요약을 작성하세요.
+주요 의사결정, 실패 경험, 필수 지식을 포함하세요:
+
+{tree_data}
+
+인수인계 요약:"""
+        
+        response = await self.provider.generate(prompt, max_tokens)
+        self.total_tokens_used += max_tokens
+        return response

package/hits_core/ai/slm_filter.py

@@ -0,0 +1,126 @@
+"""SLM-based pre-filter for token cost optimization."""
+
+from typing import Optional
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ContentImportance(str, Enum):
+    CRITICAL = "critical"
+    IMPORTANT = "important"
+    NOISE = "noise"
+
+
+@dataclass
+class FilterResult:
+    content: str
+    importance: ContentImportance
+    confidence: float
+    keywords: list[str]
+
+
+CRITICAL_KEYWORDS = [
+    "장애", "에러", "버그", "핫픽스", "긴급", "중단", "실패",
+    "롤백", "복구", "보안", "취약점", "인증", "권한",
+]
+
+IMPORTANT_KEYWORDS = [
+    "배포", "빌드", "테스트", "설정", "구성", "변경",
+    "업데이트", "수정", "개선", "최적화", "성능",
+]
+
+NOISE_PATTERNS = [
+    "로그:", "debug:", "trace:", "info:",
+    "TODO:", "FIXME:", "XXX:",
+]
+
+
+class SLMFilter:
+    def __init__(
+        self,
+        critical_threshold: float = 0.7,
+        important_threshold: float = 0.5,
+    ):
+        self.critical_threshold = critical_threshold
+        self.important_threshold = important_threshold
+    
+    def classify(self, content: str) -> FilterResult:
+        if not content:
+            return FilterResult(
+                content=content,
+                importance=ContentImportance.NOISE,
+                confidence=1.0,
+                keywords=[],
+            )
+        
+        keywords = []
+        critical_score = 0.0
+        important_score = 0.0
+        noise_score = 0.0
+        
+        content_lower = content.lower()
+        
+        for keyword in CRITICAL_KEYWORDS:
+            if keyword in content:
+                critical_score += 1.0
+                keywords.append(keyword)
+        
+        for keyword in IMPORTANT_KEYWORDS:
+            if keyword in content:
+                important_score += 0.5
+                keywords.append(keyword)
+        
+        for pattern in NOISE_PATTERNS:
+            if pattern.lower() in content_lower:
+                noise_score += 0.5
+        
+        total_chars = max(len(content), 1)
+        
+        # Score normalization: each keyword contributes meaningfully
+        # Critical: even 1 keyword should be enough for critical content
+        critical_score = min(critical_score / 2.0, 1.0)
+        important_score = min(important_score / 3.0, 1.0)
+        noise_score = min(noise_score / 1.0, 1.0)
+        
+        # Decision: critical takes priority over noise
+        # "긴급 장애 발생" has both critical and noise-like exclamation
+        # but the critical keywords should dominate
+        if critical_score > 0:
+            importance = ContentImportance.CRITICAL
+            confidence = critical_score
+        elif noise_score > important_score and noise_score >= 0.5:
+            importance = ContentImportance.NOISE
+            confidence = noise_score
+        elif important_score > 0:
+            importance = ContentImportance.IMPORTANT
+            confidence = important_score
+        else:
+            importance = ContentImportance.IMPORTANT
+            confidence = 0.5
+        
+        return FilterResult(
+            content=content,
+            importance=importance,
+            confidence=confidence,
+            keywords=keywords,
+        )
+    
+    def filter_batch(self, contents: list[str]) -> tuple[list[str], list[str]]:
+        critical_important = []
+        noise = []
+        
+        for content in contents:
+            result = self.classify(content)
+            if result.importance in (ContentImportance.CRITICAL, ContentImportance.IMPORTANT):
+                critical_important.append(content)
+            else:
+                noise.append(content)
+        
+        return critical_important, noise
+    
+    def estimate_filter_ratio(self, contents: list[str]) -> float:
+        if not contents:
+            return 0.0
+        
+        critical_important, _ = self.filter_batch(contents)
+        return len(critical_important) / len(contents)

package/hits_core/api/__init__.py

@@ -0,0 +1,3 @@
+from .server import start_api_server, stop_api_server
+
+__all__ = ["start_api_server", "stop_api_server"]

package/hits_core/api/routes/__init__.py

@@ -0,0 +1,8 @@
+from . import health
+from . import work_log
+from . import node
+from . import handover
+from . import auth
+from . import knowledge
+
+__all__ = ["health", "work_log", "node", "handover", "auth", "knowledge"]

package/hits_core/api/routes/auth.py

@@ -0,0 +1,211 @@
+"""Authentication API routes.
+
+Endpoints:
+- POST /api/auth/register  → Create user (first user becomes admin)
+- POST /api/auth/login     → Authenticate, set HttpOnly cookies
+- POST /api/auth/logout    → Clear auth cookies
+- POST /api/auth/refresh   → Refresh access token
+- GET  /api/auth/me        → Get current user info
+- PUT  /api/auth/password  → Change password
+"""
+
+from fastapi import APIRouter, Request, Response, HTTPException, Depends, status
+from pydantic import BaseModel, Field
+from typing import Any, Optional
+
+from hits_core.auth.manager import get_auth_manager
+from hits_core.auth.dependencies import get_current_user, require_auth
+
+
+router = APIRouter()
+
+
+# --- Request/Response Models ---
+
+class RegisterRequest(BaseModel):
+    username: str = Field(..., min_length=3, max_length=32, pattern=r"^[a-zA-Z0-9_-]+$")
+    password: str = Field(..., min_length=8, max_length=128)
+
+
+class LoginRequest(BaseModel):
+    username: str = Field(..., min_length=1)
+    password: str = Field(..., min_length=1)
+
+
+class ChangePasswordRequest(BaseModel):
+    old_password: str = Field(..., min_length=1)
+    new_password: str = Field(..., min_length=8, max_length=128)
+
+
+class APIResponse(BaseModel):
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+
+
+# --- Cookie Settings ---
+# Secure cookies: HttpOnly (no JS access), Secure (HTTPS only in prod),
+# SameSite=Lax (CSRF protection), path restricted to /api
+def _cookie_params(secure: bool = False) -> dict:
+    return {
+        "httponly": True,
+        "secure": secure,
+        "samesite": "lax",
+        "path": "/",
+        "max_age": None,  # session cookie for access
+    }
+
+
+# --- Endpoints ---
+
+@router.post("/auth/register", response_model=APIResponse)
+async def register(body: RegisterRequest, request: Request):
+    """Register a new user. First user automatically becomes admin."""
+    auth = get_auth_manager()
+
+    if auth.has_any_user():
+        # Registration requires auth after first user
+        user = await get_current_user(request)
+        if not user or user.get("role") != "admin":
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Only admins can create new users",
+            )
+
+    if auth.user_exists(body.username):
+        return APIResponse(success=False, error="Username already exists")
+
+    success = auth.create_user(body.username, body.password)
+    if not success:
+        return APIResponse(success=False, error="Failed to create user")
+
+    return APIResponse(
+        success=True,
+        data={
+            "username": body.username,
+            "role": "admin" if not auth.has_any_user() else "user",
+            "message": "User created successfully",
+        },
+    )
+
+
+@router.post("/auth/login", response_model=APIResponse)
+async def login(body: LoginRequest, response: Response):
+    """Authenticate and set HttpOnly JWT cookies."""
+    auth = get_auth_manager()
+    tokens = auth.create_tokens(body.username, body.password)
+
+    if not tokens:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid username or password",
+        )
+
+    # Set HttpOnly cookies
+    # Access token: short-lived (15 min)
+    response.set_cookie(
+        key="access_token",
+        value=tokens["access_token"],
+        httponly=True,
+        secure=False,  # Set True in production with HTTPS
+        samesite="lax",
+        path="/",
+        max_age=900,  # 15 minutes
+    )
+
+    # Refresh token: long-lived (7 days)
+    response.set_cookie(
+        key="refresh_token",
+        value=tokens["refresh_token"],
+        httponly=True,
+        secure=False,  # Set True in production with HTTPS
+        samesite="lax",
+        path="/api/auth/refresh",  # Only sent to refresh endpoint
+        max_age=604800,  # 7 days
+    )
+
+    return APIResponse(
+        success=True,
+        data={
+            "username": tokens["username"],
+            "role": tokens["role"],
+        },
+    )
+
+
+@router.post("/auth/logout", response_model=APIResponse)
+async def logout(response: Response):
+    """Clear authentication cookies."""
+    response.delete_cookie(key="access_token", path="/")
+    response.delete_cookie(key="refresh_token", path="/api/auth/refresh")
+    return APIResponse(success=True, data={"message": "Logged out"})
+
+
+@router.post("/auth/refresh", response_model=APIResponse)
+async def refresh_token(request: Request, response: Response):
+    """Refresh access token using refresh token cookie."""
+    refresh_token = request.cookies.get("refresh_token")
+    if not refresh_token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="No refresh token",
+        )
+
+    auth = get_auth_manager()
+    new_access = auth.refresh_access_token(refresh_token)
+
+    if not new_access:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired refresh token",
+        )
+
+    response.set_cookie(
+        key="access_token",
+        value=new_access,
+        httponly=True,
+        secure=False,
+        samesite="lax",
+        path="/",
+        max_age=900,
+    )
+
+    return APIResponse(success=True, data={"message": "Token refreshed"})
+
+
+@router.get("/auth/me", response_model=APIResponse)
+async def get_me(user: dict = Depends(require_auth)):
+    """Get current authenticated user info."""
+    return APIResponse(success=True, data=user)
+
+
+@router.put("/auth/password", response_model=APIResponse)
+async def change_password(
+    body: ChangePasswordRequest,
+    user: dict = Depends(require_auth),
+):
+    """Change password for the authenticated user."""
+    auth = get_auth_manager()
+    success = auth.change_password(user["username"], body.old_password, body.new_password)
+
+    if not success:
+        return APIResponse(success=False, error="Invalid current password")
+
+    return APIResponse(success=True, data={"message": "Password changed"})
+
+
+@router.get("/auth/status", response_model=APIResponse)
+async def auth_status(request: Request):
+    """Check if authentication is initialized (has any users)."""
+    auth = get_auth_manager()
+    user = await get_current_user(request)
+
+    return APIResponse(
+        success=True,
+        data={
+            "initialized": auth.has_any_user(),
+            "authenticated": user is not None,
+            "username": user.get("username") if user else None,
+            "role": user.get("role") if user else None,
+        },
+    )