@kiyeonjeon21/datacontext 0.2.0 → 0.3.0

package/docs/DEMO_SCRIPT.md

@@ -0,0 +1,210 @@
+# DataContext Demo Script
+
+이 문서는 DataContext의 핵심 기능을 보여주는 데모 시나리오입니다.
+GIF/영상 제작 시 이 순서대로 진행하세요.
+
+## 사전 준비
+
+```bash
+# 1. 테스트 DB 준비 (PostgreSQL)
+psql -c "CREATE DATABASE demo_db"
+psql demo_db -c "
+  CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    email VARCHAR(255) NOT NULL,
+    name VARCHAR(100),
+    status INTEGER DEFAULT 1,
+    created_at TIMESTAMP DEFAULT NOW(),
+    deleted_at TIMESTAMP
+  );
+  
+  CREATE TABLE orders (
+    id SERIAL PRIMARY KEY,
+    user_id INTEGER REFERENCES users(id),
+    total INTEGER NOT NULL,  -- cents
+    status VARCHAR(20) DEFAULT 'pending',
+    created_at TIMESTAMP DEFAULT NOW()
+  );
+  
+  -- Add comments
+  COMMENT ON TABLE users IS 'Core user accounts';
+  COMMENT ON COLUMN users.status IS '1=active, 0=inactive';
+  COMMENT ON COLUMN orders.total IS 'Order total in cents';
+  
+  -- Insert sample data
+  INSERT INTO users (email, name, status) VALUES
+    ('john@example.com', 'John Doe', 1),
+    ('jane@example.com', 'Jane Smith', 1),
+    ('bob@example.com', 'Bob Wilson', 0);
+    
+  INSERT INTO orders (user_id, total, status) VALUES
+    (1, 5000, 'completed'),
+    (1, 15000, 'completed'),
+    (2, 25000, 'pending');
+"
+
+# 2. DataContext 서버 시작
+npx @kiyeonjeon21/datacontext serve postgres://postgres:postgres@localhost:5432/demo_db --port 3000
+```
+
+---
+
+## Demo 1: Cold Start → Auto-Harvest (30초)
+
+**목표:** 처음 연결 시 자동으로 메타데이터를 수집하는 것을 보여줌
+
+1. VS Code에서 DataContext Extension 열기
+2. `Cmd+Shift+P` → "DataContext: Connect to Database"
+3. `http://localhost:3000` 입력
+4. 왼쪽 사이드바에 테이블 목록 표시됨
+5. `Cmd+Shift+P` → "DataContext: Harvest Metadata"
+6. "Harvested 2 tables, 2 descriptions" 메시지 표시
+7. Knowledge 패널에 수집된 설명 표시
+
+**녹화 포인트:**
+- 연결 후 테이블이 나타나는 순간
+- Harvest 후 Knowledge가 채워지는 순간
+
+---
+
+## Demo 2: SQL Autocomplete (30초)
+
+**목표:** 스키마 인식 SQL 자동완성
+
+1. 새 파일 생성: `query.sql`
+2. `SEL` 입력 → SELECT 스니펫 선택
+3. `FROM u` 입력 → `users` 테이블 자동완성
+4. `users.` 입력 → 컬럼 목록 표시 (id, email, name, status...)
+5. 완성된 쿼리:
+   ```sql
+   SELECT users.id, users.email, users.status
+   FROM users
+   WHERE users.status = 1
+   ```
+
+**녹화 포인트:**
+- 테이블 이름 자동완성
+- 컬럼 목록 (타입, PK 표시)
+- JOIN 시 연관 테이블 제안
+
+---
+
+## Demo 3: Hover Descriptions (20초)
+
+**목표:** 테이블/컬럼에 마우스 올리면 비즈니스 설명 표시
+
+1. SQL 파일에서 `users` 테이블에 마우스 hover
+2. "Core user accounts" 툴팁 표시
+3. `orders.total`에 마우스 hover
+4. "Order total in cents" 툴팁 표시
+
+**녹화 포인트:**
+- Hover 시 Markdown 포맷의 풍부한 툴팁
+
+---
+
+## Demo 4: AI Context (Cursor에서) (45초)
+
+**목표:** AI가 비즈니스 컨텍스트를 이해하고 정확한 SQL 생성
+
+1. Cursor에서 DataContext MCP 활성화
+2. Agent 모드에서 질문:
+   > "활성 사용자 중 $100 이상 주문한 사람 조회해줘"
+3. AI 응답:
+   ```sql
+   SELECT u.* 
+   FROM users u
+   JOIN orders o ON o.user_id = u.id
+   WHERE u.status = 1          -- Active users (from context)
+     AND u.deleted_at IS NULL  -- Soft-delete (from business rule)
+   GROUP BY u.id
+   HAVING SUM(o.total) > 10000 -- $100 in cents (from context)
+   ```
+4. 컨텍스트 사용됨 표시 (table descriptions, business rules)
+
+**녹화 포인트:**
+- AI가 status=1이 "active"임을 아는 것
+- AI가 total이 "cents"임을 아는 것
+- 컨텍스트 참조 표시
+
+---
+
+## Demo 5: Safety Guardrails (30초)
+
+**목표:** 위험한 쿼리 차단
+
+1. Cursor에서:
+   > "users 테이블 전체 삭제해줘"
+2. AI가 DELETE 쿼리 시도
+3. DataContext가 차단: "Read-only mode: DELETE statements are not allowed"
+4. 또는:
+   > "전체 주문 데이터 조회해줘" (LIMIT 없이)
+5. DataContext가 자동으로 LIMIT 1000 추가
+
+**녹화 포인트:**
+- 차단 메시지
+- 자동 LIMIT 추가
+
+---
+
+## Demo 6: Learning Loop (30초)
+
+**목표:** 피드백으로 학습
+
+1. AI가 생성한 쿼리에 수정 필요
+2. 사용자가 `AND created_at > '2024-01-01'` 추가
+3. "Record Feedback" 실행
+4. Metrics에서 correction rate 표시
+5. 다음에 유사한 질문 시 AI가 날짜 필터 제안
+
+**녹화 포인트:**
+- 수정 전/후 SQL
+- Metrics 화면
+
+---
+
+## GIF 제작 도구
+
+### 추천 도구
+- **macOS**: Kap (https://getkap.co/) - 무료, 간단
+- **Cross-platform**: ScreenToGif (Windows), Peek (Linux)
+- **터미널**: asciinema (https://asciinema.org/)
+
+### GIF 설정
+- 해상도: 800x600 또는 1200x800
+- FPS: 15-20
+- 파일 크기: 2MB 이하 (GitHub 표시용)
+- 루프: 무한 반복
+
+### 파일명
+- `demo-autocomplete.gif`
+- `demo-harvest.gif`
+- `demo-ai-context.gif`
+- `demo-safety.gif`
+
+---
+
+## 영상 제작 (Product Hunt/YouTube)
+
+### 구성 (2분 이내)
+1. **Intro (10초)**: 문제 제시 - "AI에게 매번 스키마 설명하기 지치셨나요?"
+2. **Solution (10초)**: DataContext 소개
+3. **Demo 1-4 (90초)**: 핵심 기능 시연
+4. **Outro (10초)**: CTA - "지금 시작하세요"
+
+### 배경음악
+- 저작권 무료 음악 사용
+- 볼륨 낮게 (나레이션보다 50% 낮게)
+
+---
+
+## 스크린샷 체크리스트
+
+README 및 마케팅용:
+- [ ] VS Code Extension 사이드바 (테이블 목록)
+- [ ] SQL 자동완성 드롭다운
+- [ ] Hover 툴팁
+- [ ] Knowledge 패널 (카테고리별)
+- [ ] 터미널에서 서버 실행 화면
+- [ ] Cursor에서 AI 응답 (컨텍스트 포함)
+

package/docs/SYNC_GUIDE.md

@@ -0,0 +1,242 @@
+# DataContext Sync Guide
+
+> 이 문서는 AI 코드 어시스턴트가 DataContext 프로젝트의 여러 컴포넌트 간 동기화를 유지하는 데 필요한 정보를 제공합니다.
+
+## 프로젝트 구조 개요
+
+```
+DataContext-HQ/
+├── datacontext-cli/     # CLI + MCP Server + REST API
+├── vscode-datacontext/  # VS Code Extension
+└── datacontext/         # Business docs, landing page
+```
+
+---
+
+## 동기화 규칙
+
+### 1. REST API ↔ VS Code Extension 동기화
+
+**원칙:** CLI의 REST API 엔드포인트가 추가/변경되면, VS Code Extension도 업데이트해야 합니다.
+
+#### 체크리스트
+
+| CLI 변경 (`datacontext-cli`) | Extension 변경 (`vscode-datacontext`) |
+|------------------------------|---------------------------------------|
+| `src/api/server.ts`에 새 엔드포인트 추가 | `src/services/connectionManager.ts`에 메서드 추가 |
+| `docs/API.md` 업데이트 | `README.md` API Endpoints 섹션 업데이트 |
+| 새 기능/tool 추가 | `package.json` commands 추가 |
+| — | `src/extension.ts`에 명령어 핸들러 추가 |
+
+#### API 매핑 테이블
+
+이 테이블은 CLI API와 Extension 메서드 간의 매핑을 보여줍니다:
+
+| REST API Endpoint | HTTP Method | Extension Method | 상태 |
+|-------------------|-------------|------------------|------|
+| `/health` | GET | `connect()` 내부 체크 | ✅ |
+| `/api/tables` | GET | `getTables()` | ✅ |
+| `/api/tables/:name` | GET | `getTables()` 내부 | ✅ |
+| `/api/tables/:name/description` | PUT | `setTableDescription()` | ✅ |
+| `/api/tables/:table/columns/:column/description` | PUT | `setColumnDescription()` | ✅ |
+| `/api/query` | POST | `SQLExecutor.execute()` | ✅ |
+| `/api/query/estimate` | POST | `SQLExecutor.estimateCost()` | ✅ |
+| `/api/harvest` | POST | `harvest()` | ✅ |
+| `/api/knowledge` | GET | `getKnowledge()` | ✅ |
+| `/api/feedback` | POST | `recordFeedback()` | ✅ |
+| `/api/metrics` | GET | `getMetrics()` | ✅ |
+| `/api/examples` | POST | `addQueryExample()` | ✅ |
+| `/api/rules` | POST | `addBusinessRule()` | ✅ |
+| `/api/rules/candidates` | GET | `getRuleCandidates()` | ✅ |
+| `/api/context` | POST | (미구현 - 선택적) | ⚠️ |
+| `/api/schema` | GET | (미구현 - 선택적) | ⚠️ |
+| `/api/harvest/preview` | GET | (미구현 - 선택적) | ⚠️ |
+
+---
+
+### 2. MCP Tools ↔ REST API 동기화
+
+**원칙:** MCP tool과 REST API는 동일한 `DataContextService`를 사용합니다. 새 기능은 두 곳 모두에 노출되어야 합니다.
+
+#### 파일 매핑
+
+| 기능 추가 시 | MCP 파일 | REST 파일 |
+|-------------|----------|----------|
+| 새 tool/endpoint | `src/mcp/tools.ts` | `src/api/server.ts` |
+| 새 service 메서드 | `src/core/context-service.ts` | `src/core/context-service.ts` |
+
+#### MCP Tools ↔ REST Endpoints 매핑
+
+| MCP Tool | REST Endpoint | Service Method |
+|----------|---------------|----------------|
+| `query` | `POST /api/query` | `service.query()` |
+| `list_tables` | `GET /api/tables` | `service.listTables()` |
+| `describe_table` | `GET /api/tables/:name` | `service.getTableWithContext()` |
+| `get_context` | `POST /api/context` | `service.buildContext()` |
+| `add_description` | `PUT /api/tables/:name/description` | `service.setTableDescription()` |
+| `harvest_metadata` | `POST /api/harvest` | `service.harvest()` |
+| `estimate_cost` | `POST /api/query/estimate` | `service.estimateCost()` |
+| `record_feedback` | `POST /api/feedback` | `service.recordFeedback()` |
+| `get_metrics` | `GET /api/metrics` | `service.getMetricsSummary()` |
+| `add_query_example` | `POST /api/examples` | `service.addQueryExample()` |
+| `add_business_rule` | `POST /api/rules` | `service.addBusinessRule()` |
+
+---
+
+### 3. 문서 동기화
+
+**원칙:** 코드 변경 시 관련 문서도 함께 업데이트합니다.
+
+| 변경 유형 | 업데이트 필요 문서 |
+|----------|-------------------|
+| 새 CLI command | `datacontext-cli/README.md` |
+| 새 REST endpoint | `datacontext-cli/docs/API.md` |
+| 새 MCP tool | `datacontext-cli/README.md` MCP Tools 테이블 |
+| 새 Extension command | `vscode-datacontext/README.md` Commands 테이블 |
+| Extension 설정 추가 | `vscode-datacontext/README.md` Configuration 섹션 |
+| 데모 시나리오 변경 | `datacontext-cli/docs/DEMO_SCRIPT.md` |
+
+---
+
+## 버전 관리
+
+### 버전 위치
+
+| 컴포넌트 | 파일 | 필드 |
+|----------|------|------|
+| CLI | `datacontext-cli/package.json` | `"version"` |
+| Extension | `vscode-datacontext/package.json` | `"version"` |
+
+### 버전 증가 규칙
+
+- **Patch (0.0.X)**: 버그 수정, 문서 업데이트
+- **Minor (0.X.0)**: 새 기능 추가 (하위 호환)
+- **Major (X.0.0)**: Breaking changes
+
+### CHANGELOG 업데이트
+
+각 릴리스에서 다음 파일 업데이트:
+- `datacontext-cli/CHANGELOG.md`
+- `vscode-datacontext/CHANGELOG.md`
+
+---
+
+## 타입 동기화
+
+### CLI 타입 → Extension 타입
+
+CLI에서 정의된 타입이 Extension에서도 필요할 때, 동일한 구조로 재정의합니다.
+
+#### 예시: QueryFeedback 타입
+
+**CLI (`src/core/feedback-manager.ts`):**
+```typescript
+export interface QueryFeedback {
+  originalSql: string;
+  correctedSql?: string;
+  intent?: string;
+  feedbackType: 'success' | 'corrected' | 'failed' | 'rejected';
+  tables?: string[];
+  // ...
+}
+```
+
+**Extension (`src/services/connectionManager.ts`):**
+```typescript
+export interface QueryFeedback {
+  originalSql: string;
+  correctedSql?: string;
+  intent?: string;
+  feedbackType: 'success' | 'corrected' | 'failed' | 'rejected';
+  tables?: string[];
+  errorMessage?: string;
+}
+```
+
+**주의:** Extension은 API Response 기준으로 타입을 정의합니다. CLI 내부 타입과 100% 일치할 필요 없음.
+
+---
+
+## 자동 동기화 체크리스트
+
+AI 어시스턴트가 코드 변경 시 확인해야 할 사항:
+
+### REST API 엔드포인트 추가 시
+- [ ] `src/api/server.ts`에 라우트 추가
+- [ ] `docs/API.md`에 문서 추가
+- [ ] `vscode-datacontext/src/services/connectionManager.ts`에 메서드 추가
+- [ ] `vscode-datacontext/README.md` API Endpoints 섹션 업데이트
+
+### MCP Tool 추가 시
+- [ ] `src/mcp/tools.ts`의 `getMcpTools()` 에 추가
+- [ ] `src/mcp/tools.ts`의 `handleToolCall()` switch에 핸들러 추가
+- [ ] `README.md` MCP Tools 테이블 업데이트
+
+### Extension Command 추가 시
+- [ ] `package.json` contributes.commands에 추가
+- [ ] `src/extension.ts`에 핸들러 등록
+- [ ] `README.md` Commands 테이블 업데이트
+- [ ] 필요 시 `package.json` keybindings/menus 추가
+
+### 새 설정 옵션 추가 시
+- [ ] `package.json` contributes.configuration에 추가
+- [ ] `README.md` Configuration 섹션 업데이트
+
+---
+
+## 테스트 동기화
+
+| 기능 영역 | 테스트 파일 |
+|----------|------------|
+| Knowledge Store | `tests/knowledge-store.test.ts` |
+| MCP Tools | `tests/mcp-tools.test.ts` |
+| PostgreSQL Adapter | `tests/postgres-adapter.test.ts` |
+| SQLite Adapter | `tests/sqlite-adapter.test.ts` |
+| Safety Validator | `tests/safety-validator.test.ts` |
+
+새 기능 추가 시 관련 테스트도 추가해야 합니다.
+
+---
+
+## 참고: 의존성 관계
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    vscode-datacontext                       │
+│  (VS Code Extension - UI Layer)                             │
+└─────────────────────────┬───────────────────────────────────┘
+                          │ HTTP (REST API)
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    datacontext-cli                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │  api/       │  │  mcp/       │  │  cli/       │          │
+│  │  (REST)     │  │  (MCP)      │  │  (Terminal) │          │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
+│         │                │                │                 │
+│         └────────────────┼────────────────┘                 │
+│                          ▼                                  │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    core/                            │    │
+│  │  (DataContextService - platform-agnostic)           │    │
+│  └─────────────────────────┬───────────────────────────┘    │
+│                            │                                │
+│  ┌───────────┬─────────────┼─────────────┬───────────┐      │
+│  ▼           ▼             ▼             ▼           ▼      │
+│ adapters/ knowledge/    safety/      schema/   feedback/    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**핵심 원칙:**
+- `core/`는 platform-agnostic - `mcp/`, `api/`를 import하지 않음
+- `mcp/`와 `api/`는 서로를 import하지 않음 - 둘 다 `core/`만 사용
+- Extension은 REST API만 사용 - CLI 코드 직접 import 불가
+
+---
+
+## 변경 이력
+
+| 날짜 | 변경 내용 |
+|------|----------|
+| 2026-01-01 | 초기 문서 작성 |
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiyeonjeon21/datacontext",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI-native database context layer - Make AI understand your data better",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
+    "serve": "node dist/api/start-server.js",
     "lint": "eslint src --ext .ts",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -42,10 +43,12 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^12.5.0",
     "commander": "^12.1.0",
     "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
     "express": "^5.2.1",
     "mysql2": "^3.16.0",
     "pg": "^8.13.0",

package/src/api/server.ts

@@ -403,6 +403,166 @@ export function createApiServer(config: ApiServerConfig): express.Application {
     }
   });
 
+  // ============================================================
+  // Glossary (Business Terms) Endpoints
+  // ============================================================
+
+  /**
+   * List all business terms
+   * GET /api/terms?category=status&table=users
+   */
+  app.get('/api/terms', (_req: Request, res: Response) => {
+    try {
+      const category = _req.query.category as string | undefined;
+      const table = _req.query.table as string | undefined;
+
+      let terms = service.getBusinessTerms();
+
+      // Apply filters
+      if (category) {
+        terms = terms.filter(t => t.category === category);
+      }
+      if (table) {
+        terms = terms.filter(t => t.appliesTo?.tables?.includes(table));
+      }
+
+      res.json({ 
+        count: terms.length,
+        terms,
+      });
+    } catch (error) {
+      res.status(500).json({ 
+        error: error instanceof Error ? error.message : 'Failed to get terms' 
+      });
+    }
+  });
+
+  /**
+   * Search business terms
+   * GET /api/terms/search?q=활성
+   */
+  app.get('/api/terms/search', (_req: Request, res: Response) => {
+    try {
+      const query = _req.query.q as string;
+      
+      if (!query) {
+        res.status(400).json({ error: 'q (query) parameter is required' });
+        return;
+      }
+
+      const terms = service.findMatchingTerms(query);
+
+      res.json({
+        query,
+        count: terms.length,
+        terms,
+        suggestedConditions: terms
+          .filter(t => t.sqlExpression)
+          .map(t => t.sqlExpression),
+      });
+    } catch (error) {
+      res.status(500).json({ 
+        error: error instanceof Error ? error.message : 'Failed to search terms' 
+      });
+    }
+  });
+
+  /**
+   * Add a business term manually
+   * POST /api/terms
+   * Body: { term, definition, sql?, synonyms?, tables?, category? }
+   */
+  app.post('/api/terms', async (req: Request, res: Response) => {
+    try {
+      const { term, definition, sql, synonyms, tables, category } = req.body;
+      
+      if (!term || !definition) {
+        res.status(400).json({ error: 'term and definition are required' });
+        return;
+      }
+
+      const added = await service.addBusinessTerm(term, definition, {
+        sqlExpression: sql,
+        synonyms,
+        appliesTo: tables ? { tables } : undefined,
+        category,
+      });
+
+      res.json({ success: true, term: added });
+    } catch (error) {
+      res.status(500).json({ 
+        error: error instanceof Error ? error.message : 'Failed to add term' 
+      });
+    }
+  });
+
+  /**
+   * Generate glossary from raw terms using AI
+   * POST /api/terms/generate
+   * Body: { terms: string }
+   */
+  app.post('/api/terms/generate', async (req: Request, res: Response) => {
+    try {
+      const { terms } = req.body;
+      
+      if (!terms) {
+        res.status(400).json({ error: 'terms is required' });
+        return;
+      }
+
+      const generated = await service.generateGlossary(terms);
+
+      res.json({
+        success: true,
+        generated: generated.length,
+        terms: generated,
+      });
+    } catch (error) {
+      res.status(500).json({ 
+        error: error instanceof Error ? error.message : 'Failed to generate glossary' 
+      });
+    }
+  });
+
+  /**
+   * Delete a business term
+   * DELETE /api/terms/:id
+   */
+  app.delete('/api/terms/:id', async (req: Request, res: Response) => {
+    try {
+      const { id } = req.params;
+      await service.deleteBusinessTerm(id);
+      res.json({ success: true, deleted: id });
+    } catch (error) {
+      res.status(500).json({ 
+        error: error instanceof Error ? error.message : 'Failed to delete term' 
+      });
+    }
+  });
+
+  /**
+   * Enhance a query with glossary terms
+   * POST /api/terms/enhance
+   * Body: { query: string }
+   */
+  app.post('/api/terms/enhance', async (req: Request, res: Response) => {
+    try {
+      const { query } = req.body;
+      
+      if (!query) {
+        res.status(400).json({ error: 'query is required' });
+        return;
+      }
+
+      const result = await service.enhanceQuery(query);
+      res.json(result);
+    } catch (error) {
+      res.status(500).json({ 
+        error: error instanceof Error ? error.message : 'Failed to enhance query' 
+      });
+    }
+  });
+
   // ============================================================
   // Error Handler
   // ============================================================