codesyncer 2.7.6 → 3.0.1

package/README.ko.md

@@ -1,6 +1,6 @@
 # CodeSyncer CLI
 
-> AI 코딩이 멍청해? 똑똑하게 만들어줌 - 영구 컨텍스트, 추론 통제, 실시간 아키텍처 동기화 for Claude Code
+> **Claude는 세션이 끝나면 모든 것을 잊습니다. CodeSyncer가 기억하게 해줍니다.**
 
 [![npm version](https://img.shields.io/npm/v/codesyncer.svg)](https://www.npmjs.com/package/codesyncer)
 [![License](https://img.shields.io/badge/License-Commons%20Clause-red.svg)](./LICENSE)
@@ -11,92 +11,142 @@
 
 ---
 
-## 🎬 데모
+## ⚡ 문제 → 해결
+
+| 문제 | CodeSyncer 없이 | CodeSyncer 사용 시 |
+|------|----------------|-------------------|
+| **맥락 손실** | 매 세션 = 처음부터 다시 | 코드 태그 = 영구 기억 |
+| **결정 망각** | "왜 JWT 썼더라?" → 🤷 | `@codesyncer-decision` → 즉시 확인 |
+| **위험한 추론** | AI가 가격, 엔드포인트, 인증 추측 | 중요 키워드 자동 일시정지 |
+| **기록 없음** | AI의 추론 이유 없음 | `codesyncer watch`가 모든 것 포착 |
 
-![CodeSyncer Demo](https://raw.githubusercontent.com/bitjaru/codesyncer/main/demo.gif)
+**결과**: 현재 프롬프트만 아는 AI가 아닌, 프로젝트를 진짜로 학습하는 AI
 
 ---
 
-## 🤔 문제 상황
+## 🎬 데모
 
-실제 프로젝트에서 AI 쓰면 이런 문제 생깁니다:
+![CodeSyncer Demo](https://raw.githubusercontent.com/bitjaru/codesyncer/main/demo-ko.gif)
 
-**1. 세션마다 컨텍스트 날아감** 😫
-- 새 AI 세션 = 처음부터 다시 설명
-- 같은 아키텍처 설명 반복
-- "API 엔드포인트가 뭐였지?" "인증은 어떻게 하지?" - 매번. 물어봄.
+---
 
-**2. 멀티레포 혼돈** 🤯
-```
-내-프로젝트/
-├── api-server/      (백엔드)
-├── web-client/      (프론트엔드)
-└── mobile-app/      (모바일)
+## 🧠 작동 원리
+
+**핵심 인사이트**: AI는 코드를 읽습니다. 그러니 맥락을 코드 안에 넣으세요.
+
+```
+┌─────────────────────────┐
+│  🧑‍💻 Claude와 코딩      │
+└───────────┬─────────────┘
+            ▼
+     ┌──────────────┐
+     │   결정함?    │
+     └──────┬───────┘
+            ▼
+┌─────────────────────────┐
+│ @codesyncer-decision    │
+│ @codesyncer-inference   │
+└───────────┬─────────────┘
+            ▼
+┌─────────────────────────┐
+│  📝 코드에 영구 저장    │
+└───────────┬─────────────┘
+            ▼
+┌─────────────────────────┐
+│  🔄 다음 세션           │
+│  Claude가 코드 읽음     │
+└───────────┬─────────────┘
+            ▼
+┌─────────────────────────┐
+│  ✅ 맥락 복구 완료!     │
+└─────────────────────────┘
 ```
-- AI는 한 번에 한 레포만 봄
-- 다른 레포의 컨텍스트 부족 → 부분적인 코드만 생성
-- "로그인 추가해줘"는 백엔드 API + 프론트 UI 둘 다 필요한데 AI는 모름
 
-**3. AI가 위험한 추론을 함** ⚠️
-- "타임아웃 30초로 설정했어요" - 어? 5초여야 하는데!
-- "/api/v1/... 사용했습니다" - 잘못된 엔드포인트!
-- 비즈니스 로직, 보안 설정, 가격 정책을 마음대로 추론
+```typescript
+// @codesyncer-decision: [2024-01-15] JWT 선택 (세션 관리가 더 간단함)
+// @codesyncer-inference: 페이지 크기 20 (일반적인 UX 패턴)
+// @codesyncer-rule: httpOnly 쿠키 사용 (XSS 방지)
+const authConfig = { /* ... */ };
+```
 
-**결과**: 설명하고 고치는 시간이 실제 코딩 시간보다 더 김
+다음 세션? Claude가 코드를 읽으면 **자동으로 모든 맥락이 복구됩니다**.
 
 ---
 
-## ✨ 해결 방법
-
-CodeSyncer는 AI에게 **전체 그림**을 제공합니다:
+## 🔥 Watch 모드: 맥락을 절대 놓치지 마세요
 
-1. **📝 코드 주석** - 모든 결정과 맥락을 코드에 직접 기록
-2. **🗂️ 마스터 문서** - 레포 간 이동과 전체 규칙 관리
-3. **📋 레포별 문서** - 각 레포만의 특별한 가이드라인
-4. **🎯 키워드 시스템** - 중요한 결정(결제, 인증 등)에서 자동 일시정지
+**문제**: Claude가 코딩하면서 태그 추가를 잊을 수 있습니다.
 
-**결과**: 복잡한 멀티레포 프로젝트에서도 **정확도 높은** AI 코딩 🎯
+**해결**: `codesyncer watch`로 태그 없는 변경을 잡아내세요.
 
----
+```bash
+codesyncer watch
+```
 
-## 🎯 CodeSyncer란?
+```
+[14:32:10] 📝 변경됨: src/utils/api.ts
+           └── ⚠️  태그 없음!
+               💡 힌트: 추론하면 @codesyncer-inference 추가
 
-CodeSyncer는 AI 코딩 어시스턴트(Claude Code 등)가 멀티 레포지토리 워크스페이스에 지능형 협업 시스템을 구축할 수 있도록 **프레임워크와 규칙**을 제공합니다.
+[14:33:22] 📝 변경됨: src/auth/login.ts
+           └── 🎯 발견: @codesyncer-decision
+               "SWR 대신 React Query 사용"
+           └── ✅ DECISIONS.md에 추가됨
+```
 
-**작동 방식:**
-1. **사용자가** CodeSyncer CLI 설치
-2. **사용자가** AI 어시스턴트 실행 (Claude Code, Cursor 등)
-3. **사용자가** `codesyncer init` 실행
-4. **AI가** 프로젝트를 분석하고 CodeSyncer 구조에 따라 문서 생성
+**왜 중요한가**: 모든 코드 변경은 맥락을 기록할 기회입니다. Watch 모드가 놓치는 것 없이 잡아냅니다.
 
-CodeSyncer는 문서가 **어디에, 어떻게** 만들어져야 하는지 정의합니다. AI 어시스턴트는 실제 코드를 분석하여 **무엇을** 작성할지 결정합니다.
+---
 
-### 주요 기능
+## ✨ 전체 기능 목록
 
-- 🤖 **AI 도구 독립적**: Claude Code, Cursor, GitHub Copilot 등 모두 지원
-- 📁 **단일 & 멀티 레포 지원**: 개별 레포지토리 또는 전체 워크스페이스 모두 지원
-- 📦 **모노레포 지원**: Turborepo, pnpm, Nx, Lerna, npm/yarn workspaces 자동 감지
-- 🔄 **Watch 모드**: 실시간 파일 모니터링 및 태그 자동 동기화
-- ✅ **Validate 명령어**: 설정 검사 및 수정 제안 (v2.7.0 신규)
-- 🏷️ **주석 태그 시스템**: `@codesyncer-*` 태그로 결정과 추론을 영구 기록
-- 🤝 **자동 의논 시스템**: 중요한 결정(결제, 보안 등)에서 자동으로 일시 정지
-- 🌐 **다국어 지원**: 한글/영문 완벽 지원
-- ⚡ **빠른 설치**: 한 번의 명령으로 전체 워크스페이스 설정
-- 🔒 **보안 강화**: 경로 탐색 공격 방지 및 입력 검증 (v2.7.0)
+| 기능 | 설명 |
+|------|------|
+| 🏷️ **태그 시스템** | `@codesyncer-decision`, `@codesyncer-inference`, `@codesyncer-rule` - 코드에 영구 맥락 |
+| 🔄 **Watch 모드** | 실시간 모니터링, 태그 없는 변경 경고, DECISIONS.md 자동 동기화 |
+| ✅ **Validate** | 태그 커버리지 확인, 누락된 문서 찾기, 수정 제안 |
+| 🤝 **자동 일시정지** | 결제/보안/인증 키워드 감지 → 코딩 전 확인 |
+| 📦 **모노레포** | Turborepo, pnpm, Nx, Lerna, npm/yarn workspaces 자동 감지 |
+| 🌐 **다국어** | 한글/영문 완벽 지원 |
+| 🔒 **보안** | 경로 탐색 방지 및 입력 검증 |
 
 ---
 
-## ⚠️ 사전 요구사항
-
-**CodeSyncer는 AI 코딩 어시스턴트가 활성화되어 있어야 합니다.**
-
-현재 지원:
+## 🔄 전체 워크플로우
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. 설정 (최초 1회)                                          │
+│     $ npm install -g codesyncer                             │
+│     $ codesyncer init                                       │
+│     → CLAUDE.md, SETUP_GUIDE.md 생성                        │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  2. AI 학습시키기 (세션마다 1회)                              │
+│     Claude Code 열고 말하기:                                 │
+│     "CLAUDE.md 읽어줘"                                       │
+│     → Claude가 태그 시스템 학습                              │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  3. 코딩 (watch 모드 실행 상태로)                            │
+│     $ codesyncer watch     ← 백그라운드 실행                 │
+│     Claude와 평소처럼 코딩                                   │
+│     → Claude가 @codesyncer-* 태그 자동 추가                  │
+│     → Watch 모드가 태그 누락 시 알림                         │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  4. 다음 세션                                                │
+│     Claude가 코드 읽음 → 태그 확인                           │
+│     → 맥락 자동 복구 완료!                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**지원 AI 도구:**
 - ✅ **Claude Code** (권장)
-- 🚧 Cursor (곧 지원 예정)
-- 🚧 GitHub Copilot (곧 지원 예정)
-- 🚧 Continue.dev (곧 지원 예정)
-
-**중요**: CodeSyncer를 사용하기 전에 AI 코딩 어시스턴트를 **실행하고 활성화**해주세요. AI가 프로젝트를 분석하고 정확한 문서를 생성하는 데 도움을 줍니다.
+- 🚧 Cursor, GitHub Copilot, Continue.dev (곧 지원 예정)
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # CodeSyncer CLI
 
-> Is your AI coding dumb? Make it smarter - Persistent project context, controlled inference, and live architecture sync for Claude Code
+> **Claude forgets everything when the session ends. CodeSyncer makes it remember.**
 
 [![npm version](https://img.shields.io/npm/v/codesyncer.svg)](https://www.npmjs.com/package/codesyncer)
 [![License](https://img.shields.io/badge/License-Commons%20Clause-red.svg)](./LICENSE)
@@ -11,92 +11,142 @@
 
 ---
 
-## 🎬 Demo
+## ⚡ The Problem → The Solution
 
-![CodeSyncer Demo](https://raw.githubusercontent.com/bitjaru/codesyncer/main/demo.gif)
+| Problem | Without CodeSyncer | With CodeSyncer |
+|---------|-------------------|-----------------|
+| **Context loss** | Every session = start from scratch | Tags in code = permanent memory |
+| **Decision amnesia** | "Why did we use JWT?" → 🤷 | `@codesyncer-decision` → instant recall |
+| **Dangerous inference** | AI guesses prices, endpoints, auth | Auto-pause on critical keywords |
+| **Untracked changes** | No record of AI's reasoning | `codesyncer watch` catches everything |
+
+**Result**: AI that actually learns your project, not just your current prompt.
 
 ---
 
-## 🤔 The Problem
+## 🎬 Demo
 
-Working with AI on real projects? You face these issues:
+![CodeSyncer Demo](https://raw.githubusercontent.com/bitjaru/codesyncer/main/demo.gif)
 
-**1. Context is lost every session** 😫
-- New AI session = Start from scratch
-- Explain the same architecture again and again
-- "What's the API endpoint?" "How does auth work?" - Every. Single. Time.
+---
 
-**2. Multi-repo chaos** 🤯
+## 🧠 How It Works
+
+**The core insight**: AI reads code. So put your context IN the code.
+
+```
+┌─────────────────────────┐
+│  🧑‍💻 Code with Claude   │
+└───────────┬─────────────┘
+            ▼
+     ┌──────────────┐
+     │  Decision?   │
+     └──────┬───────┘
+            ▼
+┌─────────────────────────┐
+│ @codesyncer-decision    │
+│ @codesyncer-inference   │
+└───────────┬─────────────┘
+            ▼
+┌─────────────────────────┐
+│  📝 Saved in code       │
+└───────────┬─────────────┘
+            ▼
+┌─────────────────────────┐
+│  🔄 Next session        │
+│  Claude reads code      │
+└───────────┬─────────────┘
+            ▼
+┌─────────────────────────┐
+│  ✅ Context recovered!  │
+└─────────────────────────┘
 ```
-my-saas-project/
-├── api-server/      (backend)
-├── web-client/      (frontend)
-└── mobile-app/      (mobile)
-```
-- AI only sees one repo at a time
-- Missing context from other repos → Fragmented code
-- "Add login" needs backend API + frontend UI, but AI doesn't know both
 
-**3. AI makes dangerous assumptions** ⚠️
-- "I'll set the timeout to 30 seconds" - Wait, should be 5!
-- "Using /api/v1/..." - Wrong endpoint!
-- Guesses business logic, security settings, pricing rules
+```typescript
+// @codesyncer-decision: [2024-01-15] Using JWT (session management is simpler)
+// @codesyncer-inference: Page size 20 (standard UX pattern)
+// @codesyncer-rule: Use httpOnly cookies (XSS prevention)
+const authConfig = { /* ... */ };
+```
 
-**Result**: You spend more time explaining and fixing than actual coding.
+Next session? Claude reads your code and **automatically recovers all context**.
 
 ---
 
-## ✨ The Solution
+## 🔥 Watch Mode: Never Lose Context Again
 
-CodeSyncer gives AI the **full picture** through:
+**Problem**: Claude might forget to add tags while coding.
 
-1. **📝 Comments in code** - All decisions and context live where they belong
-2. **🗂️ Master document** - Cross-repo navigation and rules
-3. **📋 Per-repo docs** - Each repo's specific guidelines
-4. **🎯 Keyword system** - Auto-pause for critical decisions (payment, auth, etc.)
+**Solution**: Run `codesyncer watch` to catch untagged changes.
 
-**Result**: AI codes with **high accuracy** even in complex multi-repo projects. 🎯
-
----
+```bash
+codesyncer watch
+```
 
-## 🎯 What is CodeSyncer?
+```
+[14:32:10] 📝 Changed: src/utils/api.ts
+           └── ⚠️  No tags!
+               💡 Hint: Add @codesyncer-inference for inferences
 
-CodeSyncer provides the **framework and rules** for AI coding assistants (like Claude Code) to set up an intelligent collaboration system across your multi-repository workspace.
+[14:33:22] 📝 Changed: src/auth/login.ts
+           └── 🎯 Found: @codesyncer-decision
+               "Use React Query instead of SWR"
+           └── ✅ Added to DECISIONS.md
+```
 
-**How it works:**
-1. **You install** CodeSyncer CLI
-2. **You launch** your AI assistant (Claude Code, Cursor, etc.)
-3. **You run** `codesyncer init`
-4. **AI analyzes** your projects and generates documentation following CodeSyncer's structure
+**Why this matters**: Every code change is an opportunity to capture context. Watch mode ensures nothing slips through.
 
-CodeSyncer defines **WHERE** and **HOW** documentation should be created. Your AI assistant fills in the **WHAT** by analyzing your actual code.
+---
 
-### Key Features
+## ✨ Full Feature List
 
-- 🤖 **AI-Agnostic**: Works with Claude Code, Cursor, GitHub Copilot, and more
-- 📁 **Single & Multi-Repository Support**: Works with individual repos or entire workspaces
-- 📦 **Monorepo Support**: Auto-detects Turborepo, pnpm, Nx, Lerna, Yarn/npm workspaces
-- 🔄 **Watch Mode**: Real-time file monitoring with auto tag sync
-- ✅ **Validate Command**: Check your setup and get fix suggestions (NEW in v2.7.0)
-- 🏷️ **Comment Tag System**: `@codesyncer-*` tags to record decisions and inferences
-- 🤝 **Discussion Auto-Pause**: Automatically stops for critical decisions (payment, security, etc.)
-- 🌐 **Multi-Language**: Full Korean and English support
-- ⚡ **Quick Setup**: One-command installation for your entire workspace
-- 🔒 **Security**: Path traversal protection and input validation (v2.7.0)
+| Feature | Description |
+|---------|-------------|
+| 🏷️ **Tag System** | `@codesyncer-decision`, `@codesyncer-inference`, `@codesyncer-rule` - permanent context in code |
+| 🔄 **Watch Mode** | Real-time monitoring, warns on untagged changes, auto-syncs to DECISIONS.md |
+| ✅ **Validate** | Check tag coverage, find missing documentation, get fix suggestions |
+| 🤝 **Auto-Pause** | Detects payment/security/auth keywords → asks before coding |
+| 📦 **Monorepo** | Auto-detects Turborepo, pnpm, Nx, Lerna, npm/yarn workspaces |
+| 🌐 **Multi-Language** | Full Korean and English support |
+| 🔒 **Security** | Path traversal protection and input validation |
 
 ---
 
-## ⚠️ Prerequisites
-
-**CodeSyncer requires an AI coding assistant to be active.**
-
-Currently supported:
+## 🔄 Complete Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. SETUP (once)                                            │
+│     $ npm install -g codesyncer                             │
+│     $ codesyncer init                                       │
+│     → Creates CLAUDE.md, SETUP_GUIDE.md                     │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  2. TEACH AI (once per session)                             │
+│     Open Claude Code and say:                               │
+│     "Read CLAUDE.md"                                        │
+│     → Claude learns the tagging system                      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  3. CODE (with watch mode running)                          │
+│     $ codesyncer watch     ← Run in background              │
+│     Code with Claude as normal                              │
+│     → Claude adds @codesyncer-* tags automatically          │
+│     → Watch mode alerts if tags are missing                 │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  4. NEXT SESSION                                            │
+│     Claude reads your code → sees the tags                  │
+│     → Context automatically recovered!                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Supported AI Tools:**
 - ✅ **Claude Code** (Recommended)
-- 🚧 Cursor (Coming soon)
-- 🚧 GitHub Copilot (Coming soon)
-- 🚧 Continue.dev (Coming soon)
-
-**Important**: Make sure your AI coding assistant is **running and active** before using CodeSyncer. The AI will analyze your projects and help generate accurate documentation.
+- 🚧 Cursor, GitHub Copilot, Continue.dev (Coming soon)
 
 ---
 

package/dist/commands/handoff.d.ts

@@ -0,0 +1,6 @@
+import { HandoffOptions } from '../types';
+/**
+ * Handoff command - save/show context for next AI session
+ */
+export declare function handoffCommand(options: HandoffOptions): Promise<void>;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/commands/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAA4B,MAAM,UAAU,CAAC;AAuRpE;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC3E"}