@vibecodetown/mcp-server 2.1.0

package/build/bootstrap/installer.js

@@ -0,0 +1,673 @@
+// adapters/mcp-ts/src/bootstrap/installer.ts
+// Download, verify, extract, and cache engine binaries
+// With self-healing: version check, retry logic, cache validation
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ENGINE_SPECS } from "./registry.js";
+import { detectPlatform, exeName } from "./platform.js";
+import { withLock } from "./lock.js";
+const execFileAsync = promisify(execFile);
+// ============================================================
+// Configuration
+// ============================================================
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(normalized);
+}
+function isOfflineMode() {
+    return isTruthyEnv(process.env.VIBECODE_OFFLINE);
+}
+function isDebugMode() {
+    return isTruthyEnv(process.env.VIBECODE_DEBUG);
+}
+// ============================================================
+// Cache Management
+// ============================================================
+/**
+ * Get platform-appropriate cache root directory
+ */
+export function cacheRoot() {
+    const override = (process.env.VIBECODE_CACHE ?? "").trim();
+    if (override) {
+        return path.resolve(override);
+    }
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Caches", "vibecode");
+    }
+    if (process.platform === "win32") {
+        return path.join(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "vibecode");
+    }
+    // linux
+    return path.join(process.env.XDG_CACHE_HOME || path.join(home, ".cache"), "vibecode");
+}
+function engineDir(name, version, platform) {
+    return path.join(cacheRoot(), "engines", name, version, platform);
+}
+function versionFile(name) {
+    return path.join(cacheRoot(), "engines", name, ".current_version");
+}
+function parseSearchPaths(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(path.delimiter)
+        .map((p) => p.trim())
+        .filter(Boolean);
+}
+async function resolveExternalBinary(name, platform) {
+    const spec = ENGINE_SPECS[name];
+    const roots = parseSearchPaths(process.env.VIBECODE_BIN_PATH);
+    if (roots.length === 0)
+        return null;
+    const exe = exeName(spec.assetPrefix);
+    const candidates = [];
+    for (const rawRoot of roots) {
+        const root = path.resolve(rawRoot);
+        candidates.push(root);
+        candidates.push(path.join(root, exe));
+        candidates.push(path.join(root, spec.assetPrefix, exe));
+    }
+    // De-dupe while preserving order
+    const seen = new Set();
+    for (const c of candidates) {
+        if (seen.has(c))
+            continue;
+        seen.add(c);
+        try {
+            const stat = await fs.promises.stat(c);
+            if (!stat.isFile())
+                continue;
+            // If user provides a direct file path, only accept it when it matches the expected executable name.
+            if (path.basename(c) !== exe)
+                continue;
+            if (await validateBinary(c)) {
+                return c;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+/**
+ * Find package root by looking for package.json
+ */
+function findPackageRoot() {
+    // Start from current module's directory
+    let dir = path.dirname(new URL(import.meta.url).pathname);
+    // On Windows, remove leading slash from /C:/...
+    if (process.platform === "win32" && dir.startsWith("/")) {
+        dir = dir.slice(1);
+    }
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path.join(dir, "package.json");
+        try {
+            if (fs.existsSync(pkgPath)) {
+                return dir;
+            }
+        }
+        catch {
+            // ignore
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Resolve embedded binary from bundled bin/ directory
+ */
+async function resolveEmbeddedBinary(name, platform) {
+    const pkgRoot = findPackageRoot();
+    if (!pkgRoot)
+        return null;
+    const spec = ENGINE_SPECS[name];
+    const binDir = path.join(pkgRoot, "bin", `${name}_${platform}`);
+    const binPath = path.join(binDir, exeName(spec.assetPrefix));
+    try {
+        if (await exists(binPath) && await validateBinary(binPath)) {
+            return binPath;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function makeBootstrapError(userMessage, internal) {
+    const debug = isDebugMode();
+    if (!debug)
+        return new Error(userMessage);
+    const detail = internal instanceof Error
+        ? internal.message
+        : typeof internal === "string"
+            ? internal
+            : internal
+                ? String(internal)
+                : "";
+    return new Error(detail ? `${userMessage}\n\n[debug] ${detail}` : userMessage);
+}
+function userMessageForBootstrapFailure(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("download_timeout") || msg.includes("AbortError")) {
+        return "다운로드 시간이 초과되었습니다. 인터넷 연결/방화벽 설정을 확인한 뒤 다시 시도해주세요.";
+    }
+    // P0-2: Better 404 error handling with recovery options
+    if (msg.includes("404") || msg.includes("no_matching_asset") || msg.includes("download_failed:404")) {
+        return `릴리스를 찾지 못했습니다.
+
+해결 방법:
+  1. VIBECODE_BIN_PATH 환경변수로 로컬 바이너리 경로 지정
+  2. VIBECODE_OFFLINE=1로 업데이트 스킵
+  3. VIBECODE_DEBUG=1로 상세 로그 확인`;
+    }
+    if (msg.startsWith("download_failed") || msg.includes("fetch")) {
+        return "다운로드에 실패했습니다. 인터넷 연결/방화벽 설정을 확인한 뒤 다시 시도해주세요.";
+    }
+    if (msg.startsWith("sha_mismatch")) {
+        return "다운로드 검증에 실패했습니다(파일 손상 가능). 잠시 후 다시 시도해주세요.";
+    }
+    if (msg.startsWith("sha_missing_for_asset")) {
+        return "다운로드 검증 정보를 찾지 못했습니다. 잠시 후 다시 시도해주세요.";
+    }
+    if (msg.startsWith("bin_not_found_after_extract")) {
+        return "설치 파일을 찾지 못했습니다. 다시 시도해도 해결되지 않으면 지원팀에 문의해주세요.";
+    }
+    return msg;
+}
+// ============================================================
+// SHA256 Verification
+// ============================================================
+function sha256File(filePath) {
+    return new Promise((resolve, reject) => {
+        const h = crypto.createHash("sha256");
+        const s = fs.createReadStream(filePath);
+        s.on("data", (d) => h.update(d));
+        s.on("error", reject);
+        s.on("end", () => resolve(h.digest("hex")));
+    });
+}
+// ============================================================
+// Network Operations with Retry
+// ============================================================
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithRetry(url, retries = MAX_RETRIES) {
+    if (isOfflineMode()) {
+        throw makeBootstrapError("오프라인 모드에서는 다운로드를 진행할 수 없습니다. 인터넷을 연결하거나, 사전 설치된 도구 경로(VIBECODE_BIN_PATH)를 지정해주세요.");
+    }
+    let lastError = null;
+    for (let attempt = 1; attempt <= retries; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+            const res = await fetch(url, { signal: controller.signal });
+            clearTimeout(timeoutId);
+            if (res.ok) {
+                return res;
+            }
+            // Server error (5xx) - retry
+            if (res.status >= 500) {
+                lastError = new Error(`server_error:${res.status}`);
+                if (attempt < retries) {
+                    await sleep(RETRY_DELAY_MS * attempt);
+                    continue;
+                }
+            }
+            // Client error (4xx) - don't retry
+            throw new Error(`download_failed:${res.status}`);
+        }
+        catch (e) {
+            lastError = e instanceof Error ? e : new Error(String(e));
+            // Abort error (timeout)
+            if (lastError.name === "AbortError") {
+                lastError = new Error("download_timeout");
+            }
+            // Network error - retry
+            if (attempt < retries && lastError.message.includes("fetch")) {
+                await sleep(RETRY_DELAY_MS * attempt);
+                continue;
+            }
+            if (attempt === retries) {
+                throw lastError;
+            }
+        }
+    }
+    throw lastError || new Error("download_failed:unknown");
+}
+async function download(url, outPath) {
+    const res = await fetchWithRetry(url);
+    await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+    const buf = Buffer.from(await res.arrayBuffer());
+    await fs.promises.writeFile(outPath, buf);
+}
+function releaseBaseUrl(repo, version) {
+    return `https://github.com/${repo}/releases/download/v${version}`;
+}
+async function readShaSums(repo, version, shaAsset) {
+    const url = `${releaseBaseUrl(repo, version)}/${shaAsset}`;
+    return readShaSumsFromUrl(url);
+}
+async function discoverRelease(repo, version) {
+    const apiBase = `https://api.github.com/repos/${repo}/releases`;
+    // Support both individual version tags and combined engine release tag
+    const tags = [`v${version}`, version, `release-${version}`, `engines-v1.0.0`];
+    if (isDebugMode()) {
+        console.log(`[debug] Discovering release for ${repo}@${version}`);
+    }
+    for (const tag of tags) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+            const res = await fetch(`${apiBase}/tags/${encodeURIComponent(tag)}`, {
+                signal: controller.signal,
+                headers: {
+                    "Accept": "application/vnd.github+json",
+                    "User-Agent": "vibecode-installer",
+                },
+            });
+            clearTimeout(timeoutId);
+            if (res.ok) {
+                const release = await res.json();
+                if (isDebugMode()) {
+                    console.log(`[debug] Found release: ${release.tag_name} with ${release.assets.length} assets`);
+                }
+                return release;
+            }
+        }
+        catch {
+            // try next tag format
+        }
+    }
+    // fallback: try latest release
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+        const res = await fetch(`${apiBase}/latest`, {
+            signal: controller.signal,
+            headers: {
+                "Accept": "application/vnd.github+json",
+                "User-Agent": "vibecode-installer",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (res.ok) {
+            const release = await res.json();
+            if (isDebugMode()) {
+                console.log(`[debug] Using latest release: ${release.tag_name}`);
+            }
+            return release;
+        }
+    }
+    catch {
+        // return null
+    }
+    return null;
+}
+function findAsset(release, name) {
+    return release.assets.find(a => a.name === name);
+}
+async function readShaSumsFromUrl(url) {
+    const res = await fetchWithRetry(url);
+    const text = await res.text();
+    const map = new Map();
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        // Format: "<sha256>  <filename>"
+        const m = t.match(/^([a-fA-F0-9]{64})\s+(.+)$/);
+        if (!m)
+            continue;
+        map.set(m[2].trim(), m[1].toLowerCase());
+    }
+    return map;
+}
+// ============================================================
+// Archive Operations
+// ============================================================
+async function extractTarGz(archivePath, destDir) {
+    await fs.promises.mkdir(destDir, { recursive: true });
+    // Windows 10+ and all unix have tar
+    await execFileAsync("tar", ["-xzf", archivePath, "-C", destDir]);
+}
+async function makeExecutable(binPath) {
+    if (process.platform === "win32")
+        return;
+    await fs.promises.chmod(binPath, 0o755);
+}
+// ============================================================
+// Version Management
+// ============================================================
+async function getCurrentVersion(name) {
+    const vFile = versionFile(name);
+    try {
+        const content = await fs.promises.readFile(vFile, "utf-8");
+        return content.trim();
+    }
+    catch {
+        return null;
+    }
+}
+async function setCurrentVersion(name, version) {
+    const vFile = versionFile(name);
+    await fs.promises.mkdir(path.dirname(vFile), { recursive: true });
+    await fs.promises.writeFile(vFile, version, "utf-8");
+}
+/**
+ * Check if engine needs update
+ */
+export async function needsUpdate(name) {
+    const spec = ENGINE_SPECS[name];
+    const current = await getCurrentVersion(name);
+    return current !== spec.version;
+}
+/**
+ * Check all engines for updates
+ */
+export async function checkUpdates() {
+    const result = {};
+    for (const name of Object.keys(ENGINE_SPECS)) {
+        const spec = ENGINE_SPECS[name];
+        const current = await getCurrentVersion(name);
+        result[name] = {
+            current,
+            required: spec.version,
+            needsUpdate: current !== spec.version
+        };
+    }
+    return result;
+}
+// ============================================================
+// Cache Validation
+// ============================================================
+/**
+ * Validate a cached binary by checking if it's executable
+ */
+async function validateBinary(binPath) {
+    try {
+        // Check file exists
+        await fs.promises.access(binPath);
+        // Check file size is reasonable (at least 1KB)
+        const stat = await fs.promises.stat(binPath);
+        if (stat.size < 1024) {
+            return false;
+        }
+        // On unix, check if executable
+        if (process.platform !== "win32") {
+            try {
+                await fs.promises.access(binPath, fs.constants.X_OK);
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate and repair cache for an engine
+ */
+async function validateAndRepair(name, platform) {
+    const spec = ENGINE_SPECS[name];
+    const dir = engineDir(name, spec.version, platform);
+    const bin = path.join(dir, exeName(spec.assetPrefix));
+    const marker = path.join(dir, ".installed");
+    // Check if installed
+    if (!(await exists(marker))) {
+        return null;
+    }
+    // Validate binary
+    if (!(await validateBinary(bin))) {
+        // Corrupted - remove marker to trigger reinstall
+        await fs.promises.rm(marker, { force: true }).catch(() => { });
+        return null;
+    }
+    return bin;
+}
+/**
+ * Validate all cached engines
+ */
+export async function validateCache() {
+    const platform = detectPlatform();
+    const result = {};
+    for (const name of Object.keys(ENGINE_SPECS)) {
+        const envBin = await resolveExternalBinary(name, platform);
+        if (envBin) {
+            result[name] = { valid: true, path: envBin };
+            continue;
+        }
+        const binPath = await validateAndRepair(name, platform);
+        result[name] = {
+            valid: binPath !== null,
+            path: binPath
+        };
+    }
+    return result;
+}
+/**
+ * Clear cache for an engine (for manual repair)
+ */
+export async function clearCache(name) {
+    const enginesDir = path.join(cacheRoot(), "engines", name);
+    await fs.promises.rm(enginesDir, { recursive: true, force: true }).catch(() => { });
+}
+/**
+ * Clear all engine caches
+ */
+export async function clearAllCaches() {
+    for (const name of Object.keys(ENGINE_SPECS)) {
+        await clearCache(name);
+    }
+}
+// ============================================================
+// Main Installation Logic
+// ============================================================
+/**
+ * Ensure all engines are installed and return their paths
+ * Thread-safe via file lock
+ * Self-healing: validates cache, auto-updates, retries on failure
+ */
+export async function ensureEngines() {
+    const platform = detectPlatform();
+    const lockPath = path.join(cacheRoot(), "locks", `install_${platform}.lock`);
+    return await withLock(lockPath, async () => {
+        const out = {};
+        for (const name of Object.keys(ENGINE_SPECS)) {
+            out[name] = await ensureOne(name, platform);
+        }
+        return out;
+    });
+}
+async function ensureOne(name, platform) {
+    const spec = ENGINE_SPECS[name];
+    const dir = engineDir(name, spec.version, platform);
+    const bin = path.join(dir, exeName(spec.assetPrefix));
+    const marker = path.join(dir, ".installed");
+    // 1. User-provided binary path (VIBECODE_BIN_PATH) - highest priority
+    const envBin = await resolveExternalBinary(name, platform);
+    if (envBin) {
+        return envBin;
+    }
+    // 2. Embedded binary (bundled in npm package) - for offline/air-gapped environments
+    const embeddedBin = await resolveEmbeddedBinary(name, platform);
+    if (embeddedBin) {
+        return embeddedBin;
+    }
+    // Check current version - auto-update if different
+    const currentVersion = await getCurrentVersion(name);
+    const needsVersionUpdate = currentVersion !== null && currentVersion !== spec.version;
+    // 3. Already cached and valid?
+    if (!needsVersionUpdate && (await exists(bin)) && (await exists(marker))) {
+        // Validate binary integrity
+        if (await validateBinary(bin)) {
+            return bin;
+        }
+        // Corrupted - remove marker to reinstall
+        await fs.promises.rm(marker, { force: true }).catch(() => { });
+    }
+    // 4. Download + verify + extract
+    if (isOfflineMode()) {
+        throw makeBootstrapError("오프라인 모드에서는 필요한 도구를 다운로드할 수 없습니다. 인터넷을 연결하거나, 사전 설치된 도구 경로(VIBECODE_BIN_PATH)를 지정해주세요.");
+    }
+    const asset = `${spec.assetPrefix}_${spec.version}_${platform}.tar.gz`;
+    const archivePath = path.join(dir, asset);
+    try {
+        // P0-2: Try GitHub API discovery first for better 404 tolerance
+        let assetUrl;
+        let shaMap;
+        const release = await discoverRelease(spec.repo, spec.version);
+        if (release) {
+            const assetInfo = findAsset(release, asset);
+            const shaInfo = findAsset(release, spec.shaSumsAsset);
+            if (assetInfo) {
+                assetUrl = assetInfo.browser_download_url;
+                // Read SHA from discovered release if available
+                if (shaInfo) {
+                    shaMap = await readShaSumsFromUrl(shaInfo.browser_download_url);
+                }
+                else {
+                    // Fallback to legacy URL for SHA
+                    shaMap = await readShaSums(spec.repo, spec.version, spec.shaSumsAsset);
+                }
+            }
+            else {
+                throw new Error(`no_matching_asset:${asset} in release ${release.tag_name}`);
+            }
+        }
+        else {
+            // Fallback to legacy URL construction
+            if (isDebugMode()) {
+                console.log(`[debug] No release found via API, using legacy URL`);
+            }
+            assetUrl = `${releaseBaseUrl(spec.repo, spec.version)}/${asset}`;
+            shaMap = await readShaSums(spec.repo, spec.version, spec.shaSumsAsset);
+        }
+        const expected = shaMap.get(asset);
+        if (!expected)
+            throw new Error(`sha_missing_for_asset:${asset}`);
+        // Clean and prepare directory
+        await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => { });
+        await fs.promises.mkdir(dir, { recursive: true });
+        // Download archive (with retry)
+        await download(assetUrl, archivePath);
+        // Verify SHA256
+        const got = (await sha256File(archivePath)).toLowerCase();
+        if (got !== expected)
+            throw new Error(`sha_mismatch:${asset}`);
+        // Extract
+        await extractTarGz(archivePath, dir);
+        // Find binary (may be at root or in subfolder)
+        const candidates = [
+            path.join(dir, exeName(spec.assetPrefix)),
+            path.join(dir, spec.assetPrefix, exeName(spec.assetPrefix))
+        ];
+        const found = await firstExisting(candidates);
+        if (!found)
+            throw new Error(`bin_not_found_after_extract:${spec.assetPrefix}`);
+        // Normalize location
+        if (found !== bin) {
+            await fs.promises.copyFile(found, bin);
+        }
+        await makeExecutable(bin);
+        await fs.promises.writeFile(marker, `ok ${new Date().toISOString()}\n`, "utf-8");
+        // Update version tracker
+        await setCurrentVersion(name, spec.version);
+        // Clean up archive to save space
+        await fs.promises.rm(archivePath, { force: true }).catch(() => { });
+        return bin;
+    }
+    catch (e) {
+        // Best-effort cleanup to avoid leaving partial installs behind.
+        await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => { });
+        throw makeBootstrapError(userMessageForBootstrapFailure(e), e);
+    }
+}
+// ============================================================
+// Utility Functions
+// ============================================================
+async function exists(p) {
+    try {
+        await fs.promises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function firstExisting(paths) {
+    for (const p of paths) {
+        if (await exists(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Get detailed health status of all engines
+ */
+export async function getEngineHealth() {
+    const platform = detectPlatform();
+    const result = [];
+    for (const name of Object.keys(ENGINE_SPECS)) {
+        const spec = ENGINE_SPECS[name];
+        const dir = engineDir(name, spec.version, platform);
+        const bin = path.join(dir, exeName(spec.assetPrefix));
+        const marker = path.join(dir, ".installed");
+        const currentVersion = await getCurrentVersion(name);
+        let status;
+        let binPath = null;
+        // External binary override path (for air-gapped/offline environments)
+        const envBin = await resolveExternalBinary(name, platform);
+        if (envBin) {
+            status = "ok";
+            binPath = envBin;
+            result.push({
+                name,
+                version: spec.version,
+                currentVersion: spec.version,
+                path: binPath,
+                status
+            });
+            continue;
+        }
+        if (!(await exists(marker))) {
+            status = "missing";
+        }
+        else if (!(await validateBinary(bin))) {
+            status = "corrupted";
+        }
+        else if (currentVersion !== spec.version) {
+            status = "needs_update";
+            binPath = bin;
+        }
+        else {
+            status = "ok";
+            binPath = bin;
+        }
+        result.push({
+            name,
+            version: spec.version,
+            currentVersion,
+            path: binPath,
+            status
+        });
+    }
+    return result;
+}

package/build/bootstrap/lock.js

@@ -0,0 +1,37 @@
+// adapters/mcp-ts/src/bootstrap/lock.ts
+// Process lock to prevent concurrent installation
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Execute function with exclusive file lock
+ * Prevents multiple MCP tool calls from racing on installation
+ */
+export async function withLock(lockPath, fn) {
+    await fs.promises.mkdir(path.dirname(lockPath), { recursive: true });
+    // Best-effort exclusive lock (cross-platform)
+    const handle = await fs.promises.open(lockPath, "wx").catch(() => null);
+    if (!handle) {
+        // Another process holds the lock - wait and retry
+        for (let i = 0; i < 80; i++) {
+            await new Promise((r) => setTimeout(r, 250));
+            const h2 = await fs.promises.open(lockPath, "wx").catch(() => null);
+            if (h2) {
+                try {
+                    return await fn();
+                }
+                finally {
+                    await h2.close().catch(() => { });
+                    await fs.promises.unlink(lockPath).catch(() => { });
+                }
+            }
+        }
+        throw new Error("lock_timeout");
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await handle.close().catch(() => { });
+        await fs.promises.unlink(lockPath).catch(() => { });
+    }
+}