@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/build/mcp/bootstrap/installer_env.d.ts

@@ -0,0 +1,19 @@
+import type { EngineName } from "./registry.js";
+export declare function getEnvInt(name: string, defaultValue: number): number;
+export declare const MAX_RETRIES: number;
+export declare const RETRY_DELAY_MS: number;
+export declare const DOWNLOAD_TIMEOUT_MS: number;
+export declare function isTruthyEnv(value: string | undefined): boolean;
+export declare function isOfflineMode(): boolean;
+export declare function isDebugMode(): boolean;
+export declare function getGitHubToken(): string | null;
+export declare function getAuthHeaders(): Record<string, string>;
+/**
+ * Get platform-appropriate cache root directory
+ */
+export declare function cacheRoot(): string;
+export declare function engineDir(name: EngineName, version: string, platform: string): string;
+export declare function versionFile(name: EngineName): string;
+export declare function parseSearchPaths(raw: string | undefined): string[];
+export declare function makeBootstrapError(userMessage: string, internal?: unknown): Error;
+export declare function userMessageForBootstrapFailure(err: unknown): string;

package/build/mcp/bootstrap/installer_env.js

@@ -0,0 +1,128 @@
+// installer_env.ts
+// Environment configuration, cache paths, and error formatting
+// Extracted from installer.ts for modularity
+import os from "node:os";
+import path from "node:path";
+import { isDownloadTimeoutError, isDownload404Error, isDownloadFailedError, } from "../errors.js";
+// ============================================================
+// Configuration (P2-26: Environment variable support)
+// ============================================================
+export function getEnvInt(name, defaultValue) {
+    const value = process.env[name];
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+// Configurable via environment variables:
+// VIBECODE_MAX_RETRIES - Maximum download retry attempts (default: 3)
+// VIBECODE_RETRY_DELAY_MS - Delay between retries in ms (default: 1000)
+// VIBECODE_DOWNLOAD_TIMEOUT_MS - Download timeout in ms (default: 60000)
+export const MAX_RETRIES = getEnvInt("VIBECODE_MAX_RETRIES", 3);
+export const RETRY_DELAY_MS = getEnvInt("VIBECODE_RETRY_DELAY_MS", 1000);
+export const DOWNLOAD_TIMEOUT_MS = getEnvInt("VIBECODE_DOWNLOAD_TIMEOUT_MS", 60_000);
+export function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(normalized);
+}
+export function isOfflineMode() {
+    return isTruthyEnv(process.env.VIBECODE_OFFLINE);
+}
+export function isDebugMode() {
+    return isTruthyEnv(process.env.VIBECODE_DEBUG);
+}
+export function getGitHubToken() {
+    return process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim() || null;
+}
+export function getAuthHeaders() {
+    const token = getGitHubToken();
+    const headers = {
+        "User-Agent": "vibecode-installer",
+    };
+    if (token) {
+        headers["Authorization"] = `token ${token}`;
+    }
+    return headers;
+}
+// ============================================================
+// 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");
+}
+export function engineDir(name, version, platform) {
+    return path.join(cacheRoot(), "engines", name, version, platform);
+}
+export function versionFile(name) {
+    return path.join(cacheRoot(), "engines", name, ".current_version");
+}
+export function parseSearchPaths(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(path.delimiter)
+        .map((p) => p.trim())
+        .filter(Boolean);
+}
+// ============================================================
+// Error Formatting
+// ============================================================
+export 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);
+}
+export function userMessageForBootstrapFailure(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // P1-4: Use centralized error patterns for consistent detection
+    if (isDownloadTimeoutError(msg)) {
+        return "다운로드 시간이 초과되었습니다. 인터넷 연결/방화벽 설정을 확인한 뒤 다시 시도해주세요.";
+    }
+    // P0-2: Better 404 error handling with recovery options
+    if (isDownload404Error(msg)) {
+        return `릴리스를 찾지 못했습니다.
+
+해결 방법:
+  1. VIBECODE_BIN_PATH 환경변수로 로컬 바이너리 경로 지정
+  2. VIBECODE_OFFLINE=1로 업데이트 스킵
+  3. VIBECODE_DEBUG=1로 상세 로그 확인`;
+    }
+    if (isDownloadFailedError(msg)) {
+        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;
+}

package/build/mcp/bootstrap/installer_network.d.ts

@@ -0,0 +1,24 @@
+export declare function sha256File(filePath: string): Promise<string>;
+export declare function sleep(ms: number): Promise<void>;
+export declare function fetchWithRetry(url: string, retries?: number, extraHeaders?: Record<string, string>): Promise<Response>;
+export declare function download(url: string, outPath: string): Promise<void>;
+export declare function releaseBaseUrl(repo: string, version: string): string;
+export declare function readShaSums(repo: string, version: string, shaAsset: string): Promise<Map<string, string>>;
+export interface GhAsset {
+    name: string;
+    browser_download_url: string;
+    url: string;
+}
+export interface GhRelease {
+    tag_name: string;
+    assets: GhAsset[];
+}
+export declare function discoverRelease(repo: string, version: string): Promise<GhRelease | null>;
+export declare function findAsset(release: GhRelease, name: string): GhAsset | undefined;
+/**
+ * Download asset from GitHub release (supports private repos with GITHUB_TOKEN)
+ */
+export declare function downloadAsset(asset: GhAsset, outPath: string): Promise<void>;
+export declare function readShaSumsFromUrl(url: string): Promise<Map<string, string>>;
+export declare function extractTarGz(archivePath: string, destDir: string): Promise<void>;
+export declare function makeExecutable(binPath: string): Promise<void>;

package/build/mcp/bootstrap/installer_network.js

@@ -0,0 +1,192 @@
+// installer_network.ts
+// Network/download operations, SHA verification, archive extraction
+// Extracted from installer.ts for modularity
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { logger } from "../../shared/logger.js";
+import { isOfflineMode, isDebugMode, getAuthHeaders, getGitHubToken, makeBootstrapError, MAX_RETRIES, RETRY_DELAY_MS, DOWNLOAD_TIMEOUT_MS, } from "./installer_env.js";
+const execFileAsync = promisify(execFile);
+// ============================================================
+// SHA256 Verification
+// ============================================================
+export 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
+// ============================================================
+export async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function fetchWithRetry(url, retries = MAX_RETRIES, extraHeaders) {
+    if (isOfflineMode()) {
+        throw makeBootstrapError("오프라인 모드에서는 다운로드를 진행할 수 없습니다. 인터넷을 연결하거나, 사전 설치된 도구 경로(VIBECODE_BIN_PATH)를 지정해주세요.");
+    }
+    let lastError = null;
+    const headers = { ...getAuthHeaders(), ...extraHeaders };
+    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, headers });
+            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");
+}
+export 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);
+}
+export function releaseBaseUrl(repo, version) {
+    return `https://github.com/${repo}/releases/download/v${version}`;
+}
+export async function readShaSums(repo, version, shaAsset) {
+    const url = `${releaseBaseUrl(repo, version)}/${shaAsset}`;
+    return readShaSumsFromUrl(url);
+}
+export 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()) {
+        logger.debug(`[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: {
+                    ...getAuthHeaders(),
+                    "Accept": "application/vnd.github+json",
+                },
+            });
+            clearTimeout(timeoutId);
+            if (res.ok) {
+                const release = await res.json();
+                if (isDebugMode()) {
+                    logger.debug(`[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: {
+                ...getAuthHeaders(),
+                "Accept": "application/vnd.github+json",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (res.ok) {
+            const release = await res.json();
+            if (isDebugMode()) {
+                logger.debug(`[debug] Using latest release: ${release.tag_name}`);
+            }
+            return release;
+        }
+    }
+    catch {
+        // return null
+    }
+    return null;
+}
+export function findAsset(release, name) {
+    return release.assets.find(a => a.name === name);
+}
+/**
+ * Download asset from GitHub release (supports private repos with GITHUB_TOKEN)
+ */
+export async function downloadAsset(asset, outPath) {
+    const token = getGitHubToken();
+    // For private repos, use API URL with Accept: application/octet-stream
+    if (token) {
+        const res = await fetchWithRetry(asset.url, MAX_RETRIES, {
+            "Accept": "application/octet-stream",
+        });
+        await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+        const buf = Buffer.from(await res.arrayBuffer());
+        await fs.promises.writeFile(outPath, buf);
+        return;
+    }
+    // For public repos, use browser_download_url
+    await download(asset.browser_download_url, outPath);
+}
+export 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
+// ============================================================
+export 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]);
+}
+export async function makeExecutable(binPath) {
+    if (process.platform === "win32")
+        return;
+    await fs.promises.chmod(binPath, 0o755);
+}

package/build/mcp/bootstrap/installer_version.d.ts

@@ -0,0 +1,54 @@
+import { type EngineName } from "./registry.js";
+import { type GhRelease } from "./installer_network.js";
+export declare function getCurrentVersion(name: EngineName): Promise<string | null>;
+export declare function setCurrentVersion(name: EngineName, version: string): Promise<void>;
+/**
+ * Check if engine needs update
+ */
+export declare function needsUpdate(name: EngineName): Promise<boolean>;
+/**
+ * Check all engines for updates
+ */
+export declare function checkUpdates(): Promise<Record<EngineName, {
+    current: string | null;
+    required: string;
+    needsUpdate: boolean;
+}>>;
+export interface RemoteEngineVersion {
+    name: EngineName;
+    version: string;
+    assetName: string;
+}
+/**
+ * Parse engine version from asset filename
+ * Format: {prefix}_{version}_{platform}.tar.gz
+ * Example: spec-high_1.0.0_linux_x64.tar.gz
+ */
+export declare function parseEngineVersionFromAsset(assetName: string): {
+    prefix: string;
+    version: string;
+    platform: string;
+} | null;
+/**
+ * Find the latest engines release from GitHub
+ */
+export declare function discoverLatestEnginesRelease(repo: string): Promise<GhRelease | null>;
+/**
+ * Extract engine versions from release assets
+ */
+export declare function extractEngineVersionsFromRelease(release: GhRelease, platform: string): Map<string, RemoteEngineVersion>;
+export interface RemoteUpdateInfo {
+    available: boolean;
+    engines: {
+        name: EngineName;
+        currentVersion: string | null;
+        remoteVersion: string;
+        needsUpdate: boolean;
+    }[];
+    releaseTag: string | null;
+}
+/**
+ * Check for remote updates from GitHub Releases
+ * This allows updates without npm package update
+ */
+export declare function checkRemoteUpdates(): Promise<RemoteUpdateInfo>;

package/build/mcp/bootstrap/installer_version.js

@@ -0,0 +1,163 @@
+// installer_version.ts
+// Version management: local version tracking and remote update discovery
+// Extracted from installer.ts for modularity
+import fs from "node:fs";
+import path from "node:path";
+import { ENGINE_SPECS } from "./registry.js";
+import { detectPlatform } from "./platform.js";
+import { logger } from "../../shared/logger.js";
+import { isOfflineMode, isDebugMode, getAuthHeaders, versionFile, DOWNLOAD_TIMEOUT_MS, } from "./installer_env.js";
+// ============================================================
+// Version Management
+// ============================================================
+export async function getCurrentVersion(name) {
+    const vFile = versionFile(name);
+    try {
+        const content = await fs.promises.readFile(vFile, "utf-8");
+        return content.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export 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;
+}
+/**
+ * Parse engine version from asset filename
+ * Format: {prefix}_{version}_{platform}.tar.gz
+ * Example: spec-high_1.0.0_linux_x64.tar.gz
+ */
+export function parseEngineVersionFromAsset(assetName) {
+    const match = assetName.match(/^(.+?)_(\d+\.\d+\.\d+)_(.+)\.tar\.gz$/);
+    if (!match)
+        return null;
+    return {
+        prefix: match[1],
+        version: match[2],
+        platform: match[3],
+    };
+}
+/**
+ * Find the latest engines release from GitHub
+ */
+export async function discoverLatestEnginesRelease(repo) {
+    if (isOfflineMode())
+        return null;
+    const apiBase = `https://api.github.com/repos/${repo}/releases`;
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+        // Get all releases and find latest engines-v* tag
+        const res = await fetch(`${apiBase}?per_page=20`, {
+            signal: controller.signal,
+            headers: {
+                ...getAuthHeaders(),
+                "Accept": "application/vnd.github+json",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!res.ok)
+            return null;
+        const releases = await res.json();
+        // Find latest engines release
+        const enginesRelease = releases.find(r => r.tag_name.startsWith("engines-v"));
+        if (enginesRelease) {
+            if (isDebugMode()) {
+                logger.debug(`[debug] Found latest engines release: ${enginesRelease.tag_name}`);
+            }
+            return enginesRelease;
+        }
+        return null;
+    }
+    catch (e) {
+        if (isDebugMode()) {
+            logger.debug(`[debug] Failed to discover latest release: ${e}`);
+        }
+        return null;
+    }
+}
+/**
+ * Extract engine versions from release assets
+ */
+export function extractEngineVersionsFromRelease(release, platform) {
+    const versions = new Map();
+    for (const asset of release.assets) {
+        const parsed = parseEngineVersionFromAsset(asset.name);
+        if (!parsed || parsed.platform !== platform)
+            continue;
+        // Map asset prefix to engine name
+        const engineName = Object.keys(ENGINE_SPECS).find(name => ENGINE_SPECS[name].assetPrefix === parsed.prefix);
+        if (engineName) {
+            versions.set(engineName, {
+                name: engineName,
+                version: parsed.version,
+                assetName: asset.name,
+            });
+        }
+    }
+    return versions;
+}
+/**
+ * Check for remote updates from GitHub Releases
+ * This allows updates without npm package update
+ */
+export async function checkRemoteUpdates() {
+    const platform = detectPlatform();
+    const result = {
+        available: false,
+        engines: [],
+        releaseTag: null,
+    };
+    // Use first engine's repo (all engines use same repo)
+    const repo = ENGINE_SPECS["spec-high"].repo;
+    const release = await discoverLatestEnginesRelease(repo);
+    if (!release) {
+        return result;
+    }
+    result.releaseTag = release.tag_name;
+    const remoteVersions = extractEngineVersionsFromRelease(release, platform);
+    for (const name of Object.keys(ENGINE_SPECS)) {
+        const currentVersion = await getCurrentVersion(name);
+        const remote = remoteVersions.get(name);
+        if (remote) {
+            const needsUpdate = currentVersion !== remote.version;
+            result.engines.push({
+                name,
+                currentVersion,
+                remoteVersion: remote.version,
+                needsUpdate,
+            });
+            if (needsUpdate) {
+                result.available = true;
+            }
+        }
+    }
+    return result;
+}

package/build/mcp/bootstrap/registry.d.ts

@@ -1,10 +1,16 @@
 export type EngineName = "spec-high" | "clinic" | "vpm-back" | "vibecoding-helper";
+export type EngineTransport = "cli" | "http" | "both";
 export type EngineSpec = {
     name: EngineName;
     version: string;
     repo: string;
     assetPrefix: string;
     shaSumsAsset: string;
+    transport: EngineTransport;
+    healthEndpoint?: string;
+    defaultPort?: number;
+    httpEnvVar?: string;
+    timeoutMs: number;
 };
 /**
  * Engine Registry (SSOT)
@@ -19,6 +25,12 @@ export declare const ENGINE_SPECS: Record<EngineName, EngineSpec>;
  *
  * Example: spec-high_1.0.0_linux_x64.tar.gz
  */
+export declare function getEngineSpec(name: EngineName): EngineSpec;
+export declare function getEngineTimeoutMs(name: EngineName): number;
+export declare function getEngineHealthEndpoint(name: EngineName): string;
+export declare function getEngineBaseUrl(name: EngineName): string | null;
+export declare function getHttpManagedEngineNames(): EngineName[];
+export declare function getHttpManagedEngineEndpoints(): string[];
 export interface SkillMeta {
     id: string;
     file: string;