@vibecodetown/mcp-server 1.3.1

package/build/mcp/tools/vibe_pm/bitnet-cache.js

@@ -0,0 +1,327 @@
+// BitNet Cache SSOT Utility
+// ===========================
+//
+// 트리거 SSOT 규칙 (BITNET_TRIGGER_SSOT.md 참조):
+// - BitNet 실행은 Observer에서만 수행한다
+// - 결과 캐시 경로: .vibe/cache/bitnet/last_check.json (legacy: .vibe/bitnet/last_check.json)
+// - source 필드는 반드시 "observer"여야 한다
+//
+// 이 유틸은 Observer ↔ CI ↔ IDE 연결고리를 고정한다.
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+import { getVibeBitnetCacheDir } from "../../paths.js";
+// ============================================================
+// Constants
+// ============================================================
+const LEGACY_CACHE_DIR = ".vibe/bitnet";
+const LAST_CHECK_FILE = "last_check.json";
+const HISTORY_FILE = "history.jsonl";
+// 캐시 유효 시간 (기본 5분)
+const DEFAULT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+// ============================================================
+// Validation
+// ============================================================
+/**
+ * source 필드가 "observer"인지 검증
+ *
+ * BITNET_TRIGGER_SSOT.md 제3조:
+ * source !== "observer" → 위반
+ */
+export function validateSource(data) {
+    return data.source === "observer";
+}
+/**
+ * BitNetLastCheck 객체 유효성 검증
+ */
+export function validateLastCheck(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const obj = data;
+    // 필수 필드 검증
+    if (typeof obj.checked_at !== "string")
+        return false;
+    if (!["GO", "WARNING", "BLOCK"].includes(obj.verdict))
+        return false;
+    if (!["NONE", "RULE", "MODEL"].includes(obj.evidence_level))
+        return false;
+    if (!Array.isArray(obj.risk_tags))
+        return false;
+    if (typeof obj.reason !== "string")
+        return false;
+    if (obj.source !== "observer")
+        return false; // 핵심 검증
+    if (!["ready", "stale", "missing"].includes(obj.ingress_state))
+        return false;
+    return true;
+}
+// ============================================================
+// Path Helpers
+// ============================================================
+/**
+ * 캐시 디렉토리 경로 반환
+ */
+export function getCacheDir(basePath) {
+    return getVibeBitnetCacheDir(basePath);
+}
+/**
+ * last_check.json 경로 반환
+ */
+export function getLastCheckPath(basePath) {
+    return path.join(getCacheDir(basePath), LAST_CHECK_FILE);
+}
+/**
+ * history.jsonl 경로 반환
+ */
+export function getHistoryPath(basePath) {
+    return path.join(getCacheDir(basePath), HISTORY_FILE);
+}
+function getLegacyLastCheckPath(basePath) {
+    return path.join(basePath, LEGACY_CACHE_DIR, LAST_CHECK_FILE);
+}
+function getLegacyHistoryPath(basePath) {
+    return path.join(basePath, LEGACY_CACHE_DIR, HISTORY_FILE);
+}
+// ============================================================
+// Read Operations
+// ============================================================
+/**
+ * 최신 검사 결과 읽기
+ *
+ * @param basePath 프로젝트 루트 경로
+ * @param staleThresholdMs 캐시 유효 시간 (기본 5분)
+ */
+export async function readLastCheck(basePath, staleThresholdMs = DEFAULT_STALE_THRESHOLD_MS) {
+    let cachePath = getLastCheckPath(basePath);
+    if (!fs.existsSync(cachePath))
+        cachePath = getLegacyLastCheckPath(basePath);
+    try {
+        if (!fs.existsSync(cachePath)) {
+            return {
+                success: false,
+                error: "CACHE_NOT_FOUND",
+            };
+        }
+        const content = await fsPromises.readFile(cachePath, "utf-8");
+        const data = JSON.parse(content);
+        // 유효성 검증
+        if (!validateLastCheck(data)) {
+            return {
+                success: false,
+                error: "INVALID_CACHE_FORMAT",
+            };
+        }
+        // source 검증 (핵심)
+        if (!validateSource(data)) {
+            return {
+                success: false,
+                error: "INVALID_SOURCE",
+            };
+        }
+        // staleness 체크
+        const checkedAt = new Date(data.checked_at).getTime();
+        const now = Date.now();
+        const stalenessMs = now - checkedAt;
+        const isStale = stalenessMs > staleThresholdMs;
+        return {
+            success: true,
+            data,
+            stale: isStale,
+            staleness_ms: stalenessMs,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : "UNKNOWN_ERROR",
+        };
+    }
+}
+/**
+ * 동기 버전 - 최신 검사 결과 읽기
+ */
+export function readLastCheckSync(basePath, staleThresholdMs = DEFAULT_STALE_THRESHOLD_MS) {
+    let cachePath = getLastCheckPath(basePath);
+    if (!fs.existsSync(cachePath))
+        cachePath = getLegacyLastCheckPath(basePath);
+    try {
+        if (!fs.existsSync(cachePath)) {
+            return {
+                success: false,
+                error: "CACHE_NOT_FOUND",
+            };
+        }
+        const content = fs.readFileSync(cachePath, "utf-8");
+        const data = JSON.parse(content);
+        if (!validateLastCheck(data)) {
+            return {
+                success: false,
+                error: "INVALID_CACHE_FORMAT",
+            };
+        }
+        if (!validateSource(data)) {
+            return {
+                success: false,
+                error: "INVALID_SOURCE",
+            };
+        }
+        const checkedAt = new Date(data.checked_at).getTime();
+        const now = Date.now();
+        const stalenessMs = now - checkedAt;
+        const isStale = stalenessMs > staleThresholdMs;
+        return {
+            success: true,
+            data,
+            stale: isStale,
+            staleness_ms: stalenessMs,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : "UNKNOWN_ERROR",
+        };
+    }
+}
+// ============================================================
+// Write Operations (Observer만 사용해야 함)
+// ============================================================
+/**
+ * 최신 검사 결과 저장
+ *
+ * 주의: 이 함수는 Observer에서만 호출해야 한다.
+ * BITNET_TRIGGER_SSOT.md 제1조 참조.
+ *
+ * @param basePath 프로젝트 루트 경로
+ * @param data 검사 결과 (source는 자동으로 "observer"로 설정됨)
+ */
+export async function writeLastCheck(basePath, data) {
+    const cacheDir = getCacheDir(basePath);
+    const cachePath = getLastCheckPath(basePath);
+    try {
+        // 디렉토리 생성
+        await fsPromises.mkdir(cacheDir, { recursive: true });
+        // source 강제 설정
+        const dataWithSource = {
+            ...data,
+            source: "observer", // 항상 observer
+        };
+        // 유효성 검증
+        if (!validateLastCheck(dataWithSource)) {
+            return {
+                success: false,
+                error: "INVALID_DATA_FORMAT",
+            };
+        }
+        // 파일 저장
+        await fsPromises.writeFile(cachePath, JSON.stringify(dataWithSource, null, 2) + "\n", "utf-8");
+        return {
+            success: true,
+            path: cachePath,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : "UNKNOWN_ERROR",
+        };
+    }
+}
+/**
+ * 이력에 항목 추가 (append-only)
+ *
+ * @param basePath 프로젝트 루트 경로
+ * @param entry 이력 항목
+ */
+export async function appendHistory(basePath, entry) {
+    const cacheDir = getCacheDir(basePath);
+    const historyPath = getHistoryPath(basePath);
+    try {
+        // 디렉토리 생성
+        await fsPromises.mkdir(cacheDir, { recursive: true });
+        // source 검증
+        if (!validateSource(entry)) {
+            return {
+                success: false,
+                error: "INVALID_SOURCE",
+            };
+        }
+        // JSONL 형식으로 추가
+        const line = JSON.stringify(entry) + "\n";
+        await fsPromises.appendFile(historyPath, line, "utf-8");
+        return {
+            success: true,
+            path: historyPath,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : "UNKNOWN_ERROR",
+        };
+    }
+}
+// ============================================================
+// Utility Functions
+// ============================================================
+/**
+ * 캐시 존재 여부 확인
+ */
+export function cacheExists(basePath) {
+    return fs.existsSync(getLastCheckPath(basePath)) || fs.existsSync(getLegacyLastCheckPath(basePath));
+}
+/**
+ * 캐시 삭제
+ */
+export async function clearCache(basePath) {
+    const cacheDir = getCacheDir(basePath);
+    try {
+        if (fs.existsSync(cacheDir)) {
+            await fsPromises.rm(cacheDir, { recursive: true });
+        }
+        const legacy = path.join(basePath, LEGACY_CACHE_DIR);
+        if (fs.existsSync(legacy)) {
+            await fsPromises.rm(legacy, { recursive: true });
+        }
+    }
+    catch {
+        // 무시
+    }
+}
+/**
+ * 이력 읽기 (최근 N개)
+ */
+export async function readHistory(basePath, limit = 100) {
+    let historyPath = getHistoryPath(basePath);
+    if (!fs.existsSync(historyPath))
+        historyPath = getLegacyHistoryPath(basePath);
+    try {
+        if (!fs.existsSync(historyPath)) {
+            return [];
+        }
+        const content = await fsPromises.readFile(historyPath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        // 최근 N개만 반환
+        const recent = lines.slice(-limit);
+        return recent.map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+export async function getCacheStatus(basePath) {
+    const result = await readLastCheck(basePath);
+    const history = await readHistory(basePath, 1000);
+    return {
+        exists: result.success,
+        last_check: result.success && result.data
+            ? {
+                verdict: result.data.verdict,
+                checked_at: result.data.checked_at,
+                stale: result.stale ?? false,
+                staleness_ms: result.staleness_ms ?? 0,
+            }
+            : undefined,
+        history_count: history.length,
+    };
+}

package/build/mcp/tools/vibe_pm/bitnet-ensure.d.ts

@@ -0,0 +1,58 @@
+export type EnsureMode = "strict" | "best_effort";
+export interface EnsureBitNetParams {
+    /** 강제 최신화 모드 */
+    mode: EnsureMode;
+    /** 프로젝트 루트 경로 */
+    workspace_root: string;
+    /** 변경된 파일 목록 (옵션, 없으면 git diff 사용) */
+    changed_files?: string[];
+    /** 캐시 TTL (ms), 기본 5분 */
+    ttl_ms?: number;
+    /** 타임아웃 (ms), 기본 30초 */
+    timeout_ms?: number;
+}
+export interface EnsureBitNetResult {
+    /** 성공 여부 */
+    success: boolean;
+    /** BitNet 결과 (있으면) */
+    output: BitNetEnsuredOutput | null;
+    /** 결과 소스 */
+    source: "fresh" | "cached" | "executed" | "failed";
+    /** 에러 메시지 (있으면) */
+    error?: string;
+    /** 캐시 staleness (ms) */
+    staleness_ms?: number;
+}
+export interface BitNetEnsuredOutput {
+    trace_id: string;
+    verdict: "GO" | "WARNING" | "BLOCK";
+    risk_tags: string[];
+    review_focus: string[];
+    confidence: number;
+    timestamp: string;
+    evidence_level: string;
+    reason: string;
+}
+/**
+ * BitNet 결과 fresh 보장
+ *
+ * strict 모드:
+ * - 캐시가 없거나 stale이면 BitNet 실행
+ * - 실행 실패 시 에러 반환
+ *
+ * best_effort 모드:
+ * - 캐시가 있으면 stale이어도 반환
+ * - 캐시가 없으면 BitNet 실행 시도
+ * - 실행 실패 시에도 null 반환 (에러 아님)
+ *
+ * @param params 파라미터
+ */
+export declare function ensureBitNetAdviceFresh(params: EnsureBitNetParams): Promise<EnsureBitNetResult>;
+/**
+ * BitNet 캐시가 fresh한지 빠르게 확인
+ */
+export declare function isBitNetFresh(basePath: string, ttlMs?: number): Promise<boolean>;
+/**
+ * BitNet 캐시 verdict 빠르게 확인
+ */
+export declare function getBitNetVerdict(basePath: string): Promise<"GO" | "WARNING" | "BLOCK" | null>;

package/build/mcp/tools/vibe_pm/bitnet-ensure.js

@@ -0,0 +1,204 @@
+// BitNet Ensure Fresh Utility
+// ===========================
+//
+// PR-B: inspect_code에서 BitNet 결과를 강제로 최신화하기 위한 유틸리티
+//
+// 모드:
+// - strict: fresh하지 않으면 BitNet 실행 (blocking)
+// - best_effort: fresh하지 않으면 캐시 결과 반환 (non-blocking)
+import { readLastCheck, } from "./bitnet-cache.js";
+import { runBitNet, } from "./bitnet-runner.js";
+// ============================================================
+// Constants
+// ============================================================
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5분
+const DEFAULT_TIMEOUT_MS = 30_000; // 30초
+// ============================================================
+// Main Function
+// ============================================================
+/**
+ * BitNet 결과 fresh 보장
+ *
+ * strict 모드:
+ * - 캐시가 없거나 stale이면 BitNet 실행
+ * - 실행 실패 시 에러 반환
+ *
+ * best_effort 모드:
+ * - 캐시가 있으면 stale이어도 반환
+ * - 캐시가 없으면 BitNet 실행 시도
+ * - 실행 실패 시에도 null 반환 (에러 아님)
+ *
+ * @param params 파라미터
+ */
+export async function ensureBitNetAdviceFresh(params) {
+    const { mode, workspace_root, changed_files, ttl_ms = DEFAULT_TTL_MS, timeout_ms = DEFAULT_TIMEOUT_MS, } = params;
+    // 1. 캐시 읽기
+    const cacheResult = await readLastCheck(workspace_root, ttl_ms);
+    // 2. 캐시가 fresh하면 바로 반환
+    if (cacheResult.success && cacheResult.data && !cacheResult.stale) {
+        return {
+            success: true,
+            output: convertToEnsuredOutput(cacheResult.data),
+            source: "fresh",
+            staleness_ms: cacheResult.staleness_ms,
+        };
+    }
+    // 3. best_effort 모드: stale 캐시라도 반환
+    if (mode === "best_effort" && cacheResult.success && cacheResult.data) {
+        return {
+            success: true,
+            output: convertToEnsuredOutput(cacheResult.data),
+            source: "cached",
+            staleness_ms: cacheResult.staleness_ms,
+        };
+    }
+    // 4. BitNet 실행 필요
+    try {
+        const runResult = await runBitNet(workspace_root, {
+            files: changed_files,
+            timeoutMs: timeout_ms,
+            saveToCache: true,
+        });
+        if (!runResult.success) {
+            // strict 모드: 실패 시 에러
+            if (mode === "strict") {
+                return {
+                    success: false,
+                    output: null,
+                    source: "failed",
+                    error: runResult.error ?? "BitNet execution failed",
+                };
+            }
+            // best_effort 모드: 실패해도 stale 캐시 반환 시도
+            if (cacheResult.success && cacheResult.data) {
+                return {
+                    success: true,
+                    output: convertToEnsuredOutput(cacheResult.data),
+                    source: "cached",
+                    staleness_ms: cacheResult.staleness_ms,
+                };
+            }
+            // 캐시도 없으면 실패
+            return {
+                success: false,
+                output: null,
+                source: "failed",
+                error: runResult.error ?? "BitNet execution failed and no cache",
+            };
+        }
+        // BitNet 실행 성공
+        return {
+            success: true,
+            output: convertRunResultToOutput(runResult),
+            source: "executed",
+        };
+    }
+    catch (e) {
+        const errorMsg = e instanceof Error ? e.message : String(e);
+        if (mode === "strict") {
+            return {
+                success: false,
+                output: null,
+                source: "failed",
+                error: errorMsg,
+            };
+        }
+        // best_effort: 예외 발생해도 캐시 반환 시도
+        if (cacheResult.success && cacheResult.data) {
+            return {
+                success: true,
+                output: convertToEnsuredOutput(cacheResult.data),
+                source: "cached",
+                staleness_ms: cacheResult.staleness_ms,
+            };
+        }
+        return {
+            success: false,
+            output: null,
+            source: "failed",
+            error: errorMsg,
+        };
+    }
+}
+// ============================================================
+// Helpers
+// ============================================================
+/**
+ * BitNetLastCheck → BitNetEnsuredOutput 변환
+ */
+function convertToEnsuredOutput(data) {
+    return {
+        trace_id: data.trace_id ?? `T-${Date.now()}`,
+        verdict: data.verdict,
+        risk_tags: data.risk_tags,
+        review_focus: extractReviewFocus(data.risk_tags),
+        confidence: calculateConfidence(data.evidence_level),
+        timestamp: data.checked_at,
+        evidence_level: data.evidence_level,
+        reason: data.reason,
+    };
+}
+/**
+ * BitNetRunResult → BitNetEnsuredOutput 변환
+ */
+function convertRunResultToOutput(result) {
+    return {
+        trace_id: result.trace_id ?? `T-${Date.now()}`,
+        verdict: result.verdict ?? "GO",
+        risk_tags: result.risk_tags ?? [],
+        review_focus: extractReviewFocus(result.risk_tags ?? []),
+        confidence: calculateConfidence(result.evidence_level ?? "NONE"),
+        timestamp: new Date().toISOString(),
+        evidence_level: result.evidence_level ?? "NONE",
+        reason: result.reason ?? "",
+    };
+}
+/**
+ * risk_tags에서 review_focus 추출
+ */
+function extractReviewFocus(riskTags) {
+    const focusMap = {
+        SECRET_DETECTED: "보안: 민감 정보 검토",
+        CONFIG_CHANGE: "설정: 구성 변경 검토",
+        DEPENDENCY_CHANGE: "의존성: 패키지 변경 검토",
+        SCHEMA_CHANGE: "스키마: DB 변경 검토",
+        API_CHANGE: "API: 인터페이스 변경 검토",
+        PERMISSION_VIOLATION: "권한: 접근 권한 검토",
+        DANGEROUS_PATTERN: "패턴: 위험 코드 검토",
+        ENV_CHANGE: "환경: 환경변수 검토",
+    };
+    return riskTags
+        .map((tag) => focusMap[tag])
+        .filter((focus) => !!focus);
+}
+/**
+ * evidence_level → confidence 변환
+ */
+function calculateConfidence(evidenceLevel) {
+    switch (evidenceLevel) {
+        case "MODEL":
+            return 0.9;
+        case "RULE":
+            return 0.7;
+        case "NONE":
+        default:
+            return 0.5;
+    }
+}
+// ============================================================
+// Quick Check Functions
+// ============================================================
+/**
+ * BitNet 캐시가 fresh한지 빠르게 확인
+ */
+export async function isBitNetFresh(basePath, ttlMs = DEFAULT_TTL_MS) {
+    const result = await readLastCheck(basePath, ttlMs);
+    return result.success && !result.stale;
+}
+/**
+ * BitNet 캐시 verdict 빠르게 확인
+ */
+export async function getBitNetVerdict(basePath) {
+    const result = await readLastCheck(basePath);
+    return result.success && result.data ? result.data.verdict : null;
+}

package/build/mcp/tools/vibe_pm/bitnet-hook-consumer.d.ts

@@ -0,0 +1,87 @@
+import { type BitNetLastCheck, type Verdict } from "./bitnet-cache.js";
+export type HookMessageFormat = "short" | "detailed";
+export type HookStatus = "GO" | "WARNING" | "BLOCK" | "NOT_AVAILABLE" | "STALE" | "INVALID_SOURCE" | "DISABLED";
+export interface HookConsumeResult {
+    /** 훅에서 사용할 상태 */
+    status: HookStatus;
+    /** 원본 verdict (캐시에서) */
+    verdict: Verdict | null;
+    /** stale 여부 */
+    stale: boolean;
+    /** staleness in minutes */
+    stalenessMinutes: number | null;
+    /** 짧은 메시지 (터미널/커밋용) */
+    shortMessage: string;
+    /** 자세한 메시지 (PR/IDE용) */
+    detailedMessage: string;
+    /** 원본 캐시 데이터 (있으면) */
+    data: BitNetLastCheck | null;
+    /** 에러 코드 (있으면) */
+    errorCode: string | null;
+    /** 훅이 exit(1)해야 하는지 */
+    shouldBlock: boolean;
+}
+/**
+ * 훅에서 BitNet 캐시 결과 소비
+ *
+ * HOOKS_CONSUMER_SPEC.md 규칙:
+ * - 캐시 읽기만 수행 (bitnet 실행 X)
+ * - source === "observer" 검증
+ * - stale 결과로 BLOCK 하지 않음
+ *
+ * @param basePath 프로젝트 루트 경로 (default: process.cwd())
+ * @param options 옵션
+ */
+export declare function consumeForHook(basePath?: string, options?: {
+    /** 캐시 TTL (ms), default: 5분 */
+    staleThresholdMs?: number;
+    /** Observer 비활성화 허용, default: true */
+    allowDisabled?: boolean;
+}): HookConsumeResult;
+/**
+ * 훅 결과를 짧은 포맷으로 반환
+ */
+export declare function getShortMessage(basePath?: string): string;
+/**
+ * 훅 결과를 자세한 포맷으로 반환
+ */
+export declare function getDetailedMessage(basePath?: string): string;
+/**
+ * 훅이 exit(1)해야 하는지 확인
+ */
+export declare function shouldBlockHook(basePath?: string): boolean;
+/**
+ * 빠른 verdict 확인 (캐시 없으면 null)
+ */
+export declare function getVerdict(basePath?: string): Verdict | null;
+/**
+ * preCheck 훅용 핸들러
+ *
+ * 사용법:
+ * ```typescript
+ * import { preCheckHook } from "@vibecodetown/mcp-server/bitnet-hook-consumer";
+ * preCheckHook();
+ * ```
+ */
+export declare function preCheckHook(basePath?: string): void;
+/**
+ * postCheck 훅용 핸들러
+ *
+ * 사용법:
+ * ```typescript
+ * import { postCheckHook } from "@vibecodetown/mcp-server/bitnet-hook-consumer";
+ * postCheckHook();
+ * ```
+ */
+export declare function postCheckHook(basePath?: string): void;
+/**
+ * CI Gate용 핸들러
+ *
+ * 사용법:
+ * ```typescript
+ * import { ciGateHook } from "@vibecodetown/mcp-server/bitnet-hook-consumer";
+ * const passed = ciGateHook();
+ * process.exit(passed ? 0 : 1);
+ * ```
+ */
+export declare function ciGateHook(basePath?: string): boolean;