@vibecodetown/mcp-server 1.3.1

package/CONTRIBUTING.md

@@ -0,0 +1,294 @@
+# Contributing to Vibe CI
+
+기여해 주셔서 감사합니다! 이 문서는 `@vibecodetown/ci` 패키지에 기여하는 방법을 설명합니다.
+
+---
+
+## 목차
+
+1. [개발 환경 설정](#개발-환경-설정)
+2. [프로젝트 구조](#프로젝트-구조)
+3. [Skillpack 시스템](#skillpack-시스템)
+4. [엔진 계약](#엔진-계약)
+5. [테스트 가이드](#테스트-가이드)
+6. [PR 체크리스트](#pr-체크리스트)
+
+---
+
+## 개발 환경 설정
+
+### 요구사항
+
+- Node.js 18.0.0+
+- TypeScript 5.x
+- Rust (엔진 개발 시)
+
+### 초기 설정
+
+```bash
+# 저장소 클론
+git clone https://github.com/vibecodetown/vibecoding-helper.git
+cd vibecoding-helper/release/mvp_core_clinic
+
+# 의존성 설치
+npm install
+
+# 빌드
+npm run build
+
+# 테스트 실행
+node build/bin/vibe-ci.js --help
+```
+
+---
+
+## 프로젝트 구조
+
+```
+release/mvp_core_clinic/
+├── bin/                          # 엔진 바이너리
+│   ├── clinic_linux_x64/         # Code Clinic (Linux)
+│   ├── clinic_win_x64/           # Code Clinic (Windows)
+│   ├── vpm-back_linux_x64/       # Spec Gate Engine (Linux)
+│   └── vpm-back_win_x64/         # Spec Gate Engine (Windows)
+│
+├── build/                        # 빌드 결과 (git ignore)
+│   ├── bin/vibe-ci.js            # CLI 엔트리포인트
+│   ├── index.js                  # 라이브러리 exports
+│   ├── skill-loader.js           # 스킬 로더
+│   ├── evidence-report.js        # Evidence 리포트
+│   └── profile-config.js         # 프로필 설정
+│
+├── docs/                         # 문서
+│   └── E2E_TEST_GUIDE.md         # E2E 테스트 가이드
+│
+├── skills/                       # Skillpack
+│   ├── skillpack.json            # 6대 보험 스킬 정의
+│   └── skillpack.schema.json     # JSON Schema
+│
+├── src/                          # TypeScript 소스
+│   ├── bin/vibe-ci.ts            # CLI 메인
+│   ├── index.ts                  # 라이브러리 exports
+│   ├── skill-loader.ts           # 스킬 로더
+│   ├── evidence-report.ts        # Evidence 리포트
+│   └── profile-config.ts         # 프로필 설정
+│
+├── package.json                  # npm 패키지 설정
+├── tsconfig.json                 # TypeScript 설정
+├── .npmignore                    # npm publish 제외 목록
+├── README.md                     # 패키지 README
+└── CONTRIBUTING.md               # 기여 가이드 (이 문서)
+```
+
+---
+
+## Skillpack 시스템
+
+### 스킬이란?
+
+스킬은 "기능"이 아니라 **고정된 루틴(동선)**입니다:
+- 허용 도구가 화이트리스트로 봉인됨
+- 반드시 Evidence(파일)를 생성/검증함
+- AI 습관 강제, 결정 압축, 반복 동선 표준화
+
+### MVP 6대 보험 스킬
+
+| skill_id | 카테고리 | 설명 |
+|----------|----------|------|
+| `GO_GATE_CHECK` | gate | 머지 승인/차단 최종 판정 |
+| `RALPH_AUTO_FIX` | recovery | 정책 기반 자동 코드 복구 |
+| `CONTEXT_RECOVERY` | context | 중단된 작업 맥락 복원 |
+| `SAFETY_POLICY_ENFORCE` | policy | 수정 허용 범위 강제 |
+| `EVIDENCE_PACKAGER` | evidence | 감사용 증거 생성 |
+| `SYSTEM_DOCTOR` | ops | 엔진 자가 진단 |
+
+### 스킬 봉인 5원칙
+
+새 스킬을 추가할 때 반드시 정의해야 하는 항목:
+
+| 원칙 | 스키마 필드 | 설명 |
+|------|------------|------|
+| 입력 스키마 | `params_schema` | 파라미터 타입 |
+| 허용 도구 | `allowed_tools` | 호출 가능한 도구 whitelist |
+| 산출물 계약 | `required_artifacts` | 생성해야 하는 파일 |
+| 실패 정책 | `failure_policy` | BLOCK/ERROR 구분 |
+| 카테고리 | `category` | gate/recovery/context/policy/evidence/ops |
+
+### 스킬 추가 예제
+
+```json
+{
+  "skill_id": "MY_NEW_SKILL",
+  "title": "새로운 스킬",
+  "category": "ops",
+  "intent": "이 스킬이 하는 일 설명",
+  "allowed_tools": [
+    { "kind": "cli", "name": "vibe-ci" }
+  ],
+  "required_artifacts": [
+    { "path": "runs/<run_id>/my/output.json", "required": true }
+  ],
+  "steps": [
+    {
+      "id": "STEP_1",
+      "title": "첫 번째 단계",
+      "kind": "preflight"
+    }
+  ],
+  "failure_policy": {
+    "default_on_missing_artifacts": "BLOCK",
+    "default_on_tool_failure": "ERROR"
+  }
+}
+```
+
+---
+
+## 엔진 계약
+
+### vpm-back 엔진
+
+**입력:**
+```bash
+vpm-back run --workspace <path> --run-id <id> [--ci] [--no-kce]
+```
+
+**출력:**
+```
+runs/<run_id>/
+├── gate/spec_gate_result.json   # 필수
+├── clinic/clinic_result.json    # 필수
+└── ingress/project_fingerprint.json
+```
+
+**spec_gate_result.json 스키마:**
+```json
+{
+  "verdict": "GO | FIX | BLOCK",
+  "exit_code": 0 | 2 | 3,
+  "failed_reasons": ["string"],
+  "issue_counts": {
+    "total": 0,
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  },
+  "evaluated_at": "ISO8601"
+}
+```
+
+### clinic 엔진
+
+**출력 (clinic_result.json):**
+```json
+{
+  "verdict": "GO | FIX | BLOCK",
+  "status": "SUCCESS | FAILED | ESCALATED | DRY_RUN",
+  "iterations": 0,
+  "lines_changed": 0,
+  "reason": "string",
+  "error": "string | null"
+}
+```
+
+### Verdict 우선순위
+
+```
+BLOCK (3) > FIX (2) > GO (0)
+```
+
+gate와 clinic 결과를 합성할 때 높은 우선순위가 최종 verdict가 됩니다.
+
+---
+
+## 테스트 가이드
+
+### 단위 테스트
+
+```bash
+# TypeScript 빌드 확인
+npm run build
+
+# CLI 기본 동작
+node build/bin/vibe-ci.js --help
+node build/bin/vibe-ci.js --json
+```
+
+### E2E 테스트
+
+자세한 내용은 [E2E_TEST_GUIDE.md](./docs/E2E_TEST_GUIDE.md)를 참조하세요.
+
+```bash
+# 테스트 프로젝트 생성
+mkdir -p /tmp/test && cd /tmp/test
+git init && echo '{}' > package.json
+
+# vibe ci 실행
+node /path/to/build/bin/vibe-ci.js --workspace . --run-id test001
+```
+
+### 엔진 테스트
+
+```bash
+# vpm-back 직접 테스트
+cd engines/vpm_back
+cargo test
+
+# clinic 직접 테스트
+cd engines/code_clinic/clinic-analyzer-rust
+cargo test
+```
+
+---
+
+## PR 체크리스트
+
+PR 제출 전 확인해주세요:
+
+### 코드 품질
+- [ ] TypeScript 빌드 성공 (`npm run build`)
+- [ ] 린트 경고 없음
+- [ ] 새 파일에 적절한 JSDoc 주석
+
+### 스킬 변경 시
+- [ ] `skillpack.json` 스키마 준수
+- [ ] `allowed_tools` 화이트리스트 정의
+- [ ] `required_artifacts` 경로 정의
+- [ ] `failure_policy` 정의
+
+### 엔진 변경 시
+- [ ] Cargo test 통과
+- [ ] 출력 JSON 스키마 준수
+- [ ] Exit code 규약 준수 (0/2/3/1)
+
+### 문서
+- [ ] README 업데이트 (필요 시)
+- [ ] CHANGELOG 항목 추가
+
+---
+
+## 코드 스타일
+
+### TypeScript
+
+- ESM 모듈 사용 (import/export)
+- 명시적 타입 선언
+- async/await 선호
+
+### Rust
+
+- `#[derive(Serialize, Deserialize)]` for JSON
+- `anyhow::Result` for error handling
+- `clap` derive pattern for CLI args
+
+---
+
+## 질문 및 지원
+
+- GitHub Issues: https://github.com/vibecodetown/vibecoding-helper/issues
+- 문서: https://vibecodetown.dev/docs
+
+---
+
+감사합니다! 🎉

package/README.md

@@ -0,0 +1,146 @@
+# Vibe PM MCP Server
+
+[![npm version](https://badge.fury.io/js/@vibecodetown%2Fmcp-server.svg)](https://www.npmjs.com/package/@vibecodetown/mcp-server)
+[![CI](https://github.com/yellowhama/vibe-pm/actions/workflows/ci.yml/badge.svg)](https://github.com/yellowhama/vibe-pm/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> AI 변경 제어 및 복구 인프라
+>
+> AI가 무엇을 했는지 추적하고, 문제가 생기면 어디서부터 잘못됐는지 찾아냅니다.
+
+---
+
+## 30초 시작
+
+```bash
+npm install -g @vibecodetown/mcp-server
+```
+
+## Claude Code 설정
+
+`~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibe-pm": {
+      "command": "npx",
+      "args": ["-y", "@vibecodetown/mcp-server"]
+    }
+  }
+}
+```
+
+Claude Code 재시작 후 `vibe_pm.status`, `vibe_pm.briefing` 등의 도구를 사용할 수 있습니다.
+
+---
+
+## 핵심 도구
+
+| 도구 | 설명 |
+|------|------|
+| `vibe_pm.briefing` | 프로젝트 시작 / 아이디어 구조화 |
+| `vibe_pm.status` | 현재 상태 요약 |
+| `vibe_pm.get_decision` | 결재 조회 (A/B/C 선택지) |
+| `vibe_pm.submit_decision` | 결재 제출 |
+| `vibe_pm.create_work_order` | 작업 지시서 생성 |
+| `vibe_pm.inspect_code` | 코드 검수 + 자동 수정 |
+| `vibe_pm.doctor` | 환경 점검 |
+| `vibe_pm.ingress` | 컨텍스트 스캔 / 재개 |
+
+---
+
+## 아키텍처
+
+```
+Claude Code ←→ MCP Server (TypeScript)
+                   ↓
+              WorkerManager
+                   ↓
+    ┌──────────────┼──────────────┐
+    ↓              ↓              ↓
+  FSWorker    BuildWorker    SearchWorker
+  (파일 스캔)   (빌드/테스트)   (웹/레포 검색)
+
+                   ↓
+              cockpitd (Rust)
+              (AI 조종석, 포트 8790)
+```
+
+---
+
+## 환경변수
+
+| 변수 | 기본값 | 설명 |
+|------|--------|------|
+| `VIBE_PROFILE` | `all` | 도구 프로파일 (`mvp`/`coding`/`all`) |
+| `VIBECODE_HELPER_MODE` | `bundled` | Helper 모드 (`off`/`bundled`/`cached`) |
+| `VIBE_OBSERVER` | `1` | Observer 활성화 (`0`=비활성) |
+| `VIBECODE_DEBUG` | - | 디버그 로그 활성화 |
+
+### 프로파일별 도구 수
+
+| 프로파일 | 도구 수 | 용도 |
+|---------|:------:|------|
+| `mvp` | 8개 | 최소 기능 |
+| `coding` | 19개 | 개발 중심 |
+| `all` | 23개 | 전체 기능 |
+
+---
+
+## 워크플로우
+
+```
+1. vibe_pm.briefing     → "프로젝트 접수했습니다"
+2. vibe_pm.get_decision → "결재가 필요합니다" (A/B/C 선택)
+3. vibe_pm.submit_decision → "결재 확정했습니다"
+4. vibe_pm.create_work_order → "작업 지시서를 뽑았습니다"
+5. [구현]
+6. vibe_pm.inspect_code → 판정
+   → GO    → "✅ 진행 가능"
+   → FIX   → "⚠️ 보완 필요" → 수정 후 재검수
+   → BLOCK → "❌ 반려" → 결재 단계로 복귀
+```
+
+---
+
+## 보안
+
+- 코드 외부 전송 없음
+- 모든 분석은 로컬에서 수행
+- 런타임 산출물은 `runs/` 폴더 (gitignore)
+
+---
+
+## 문서
+
+| 문서 | 설명 |
+|------|------|
+| [Agent Guide](docs/agent-guide.md) | AI 에이전트용 가이드 |
+| [Features](docs/features.md) | 기능 상세 |
+| [Timeline](docs/timeline.md) | 기능 활성화 시점 |
+| [Positioning](docs/positioning.md) | FAQ & 비교 |
+
+---
+
+## 개발
+
+```bash
+# 설치
+npm ci
+
+# 빌드
+npm run build
+
+# 테스트
+npm test
+
+# 린트
+npm run lint
+```
+
+---
+
+## 라이선스
+
+MIT

package/build/background-sync-worker.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Background Sync Worker
+ *
+ * 오프라인 동기화 큐 관리 및 서버 전송 (FAIL-SAFE)
+ *
+ * 구현 원칙:
+ * - 큐 로직은 OfflineQueue(SSOT)에 위임
+ * - 전송 로직은 sendEncryptedPacket(SSOT)에 위임 (http/https 모두 지원)
+ *
+ * @see docs/DEV_SPEC/0127/MVP_CORE/specs/BACKGROUND_SYNC_AND_DEEP_LINK_SPEC_v1.0.md
+ */
+import type { EncryptedPacket } from "./sync-packet-builder.js";
+import { type QueueDrainResult } from "./offline-queue.js";
+export interface SyncWorkerOptions {
+    /** 서버 엔드포인트 */
+    endpoint?: string;
+    /** 인증 토큰 (Authorization: Bearer ...) */
+    licenseKey?: string;
+    /** 요청 타임아웃 (ms) */
+    timeout?: number;
+    /** 큐 디렉토리 (테스트용) */
+    queueDir?: string;
+}
+export interface SyncResult extends QueueDrainResult {
+}
+export declare class BackgroundSyncWorker {
+    private endpoint;
+    private authToken;
+    private timeoutMs;
+    private queue;
+    constructor(options?: SyncWorkerOptions);
+    queuePacket(packet: EncryptedPacket): Promise<void>;
+    flushQueue(): Promise<SyncResult>;
+    /**
+     * 큐 상태 조회 (best-effort)
+     */
+    getQueueStatus(): {
+        pending: number;
+        dlq: number;
+        oldest?: string;
+    };
+    /**
+     * 오래된 패킷 정리 (legacy helper)
+     */
+    cleanupOldPackets(): Promise<number>;
+    /**
+     * DLQ 재처리 (best-effort)
+     */
+    reprocessDlq(): Promise<number>;
+}
+export declare function flushQueueInBackground(options?: SyncWorkerOptions): void;
+export declare function queueAndFlush(packet: EncryptedPacket, options?: SyncWorkerOptions): Promise<void>;
+export declare function getQueueDir(): string;
+export declare function getDlqDir(): string;
+export default BackgroundSyncWorker;

package/build/background-sync-worker.js

@@ -0,0 +1,172 @@
+/**
+ * Background Sync Worker
+ *
+ * 오프라인 동기화 큐 관리 및 서버 전송 (FAIL-SAFE)
+ *
+ * 구현 원칙:
+ * - 큐 로직은 OfflineQueue(SSOT)에 위임
+ * - 전송 로직은 sendEncryptedPacket(SSOT)에 위임 (http/https 모두 지원)
+ *
+ * @see docs/DEV_SPEC/0127/MVP_CORE/specs/BACKGROUND_SYNC_AND_DEEP_LINK_SPEC_v1.0.md
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { OfflineQueue, getDefaultQueueDir } from "./offline-queue.js";
+import { sendEncryptedPacket } from "./sync-manager.js";
+// ============================================================================
+// Constants
+// ============================================================================
+/** 기본 엔드포인트 */
+const DEFAULT_ENDPOINT = "https://api.vibecodetown.dev/api/v1/sync";
+/** 요청 타임아웃 (ms) */
+const REQUEST_TIMEOUT_MS = 30_000;
+/** User-Agent */
+const USER_AGENT = "vibe-ci/1.0.0";
+/** 패킷 최대 보관 일수 (legacy helper) */
+const MAX_AGE_DAYS = 7;
+// ============================================================================
+// BackgroundSyncWorker
+// ============================================================================
+export class BackgroundSyncWorker {
+    endpoint;
+    authToken;
+    timeoutMs;
+    queue;
+    constructor(options) {
+        this.endpoint = options?.endpoint ?? DEFAULT_ENDPOINT;
+        this.authToken = options?.licenseKey ?? null;
+        this.timeoutMs = options?.timeout ?? REQUEST_TIMEOUT_MS;
+        this.queue = new OfflineQueue({
+            queueDir: options?.queueDir ?? getDefaultQueueDir(),
+            // other OfflineQueue options keep defaults (max retries/ttl/backoff)
+        });
+    }
+    async queuePacket(packet) {
+        await this.queue.enqueue(packet);
+    }
+    async flushQueue() {
+        return await this.queue.drain(async (packet) => {
+            return await sendEncryptedPacket(packet, {
+                endpoint: this.endpoint,
+                authToken: this.authToken,
+                timeoutMs: this.timeoutMs,
+                userAgent: USER_AGENT,
+            });
+        });
+    }
+    /**
+     * 큐 상태 조회 (best-effort)
+     */
+    getQueueStatus() {
+        const stats = this.queue.stats();
+        const queueDir = this.queue.getQueueDir();
+        let oldest;
+        try {
+            const files = fs.readdirSync(queueDir).filter((f) => f.endsWith(".json")).sort();
+            const first = files[0];
+            if (first) {
+                const raw = fs.readFileSync(path.join(queueDir, first), "utf-8");
+                const queued = JSON.parse(raw);
+                if (queued?.queuedAt)
+                    oldest = String(queued.queuedAt);
+            }
+        }
+        catch {
+            // ignore
+        }
+        return { pending: stats.queued, dlq: stats.dlq, oldest };
+    }
+    /**
+     * 오래된 패킷 정리 (legacy helper)
+     */
+    async cleanupOldPackets() {
+        let cleaned = 0;
+        const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+        for (const dir of [this.queue.getQueueDir(), this.queue.getDlqDir()]) {
+            let files = [];
+            try {
+                files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                const filePath = path.join(dir, file);
+                try {
+                    const raw = fs.readFileSync(filePath, "utf-8");
+                    const queued = JSON.parse(raw);
+                    const queuedAt = new Date(String(queued.queuedAt ?? "")).getTime();
+                    if (!Number.isFinite(queuedAt) || queuedAt < cutoff) {
+                        fs.unlinkSync(filePath);
+                        cleaned++;
+                    }
+                }
+                catch {
+                    try {
+                        fs.unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * DLQ 재처리 (best-effort)
+     */
+    async reprocessDlq() {
+        let requeued = 0;
+        const dlqDir = this.queue.getDlqDir();
+        const queueDir = this.queue.getQueueDir();
+        let files = [];
+        try {
+            files = fs.readdirSync(dlqDir).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            return 0;
+        }
+        for (const file of files) {
+            const dlqPath = path.join(dlqDir, file);
+            const queuePath = path.join(queueDir, file);
+            try {
+                const raw = fs.readFileSync(dlqPath, "utf-8");
+                const queued = JSON.parse(raw);
+                queued.retryCount = 0;
+                delete queued.lastError;
+                fs.writeFileSync(queuePath, JSON.stringify(queued, null, 2), "utf-8");
+                fs.unlinkSync(dlqPath);
+                requeued++;
+            }
+            catch {
+                // ignore
+            }
+        }
+        return requeued;
+    }
+}
+// ============================================================================
+// Fire-and-Forget Helper
+// ============================================================================
+export function flushQueueInBackground(options) {
+    const worker = new BackgroundSyncWorker(options);
+    worker.flushQueue().catch(() => {
+        // Fire-and-forget: 에러 무시
+    });
+}
+export async function queueAndFlush(packet, options) {
+    const worker = new BackgroundSyncWorker(options);
+    await worker.queuePacket(packet);
+    worker.flushQueue().catch(() => {
+        // Fire-and-forget: 에러 무시
+    });
+}
+export function getQueueDir() {
+    return getDefaultQueueDir();
+}
+export function getDlqDir() {
+    return path.join(getDefaultQueueDir(), "dlq");
+}
+export default BackgroundSyncWorker;

package/build/bin/vibe-auth.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Vibe Auth CLI
+ *
+ * License management commands
+ *
+ * Usage:
+ *   vibe auth activate <LICENSE_KEY>   Activate license
+ *   vibe auth status [--json]          Check status
+ *   vibe auth logout                   Remove local license file
+ */
+export {};