@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/build/mcp/bootstrap/installer.js

@@ -2,93 +2,182 @@
 // 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";
-import { isDownloadTimeoutError, isDownload404Error, isDownloadFailedError, } from "../errors.js";
-const execFileAsync = promisify(execFile);
+import { logger } from "../../shared/logger.js";
+// Re-export environment config
+export { cacheRoot, isDebugMode, isOfflineMode, getGitHubToken, getAuthHeaders, engineDir, versionFile, parseSearchPaths, makeBootstrapError, userMessageForBootstrapFailure, } from "./installer_env.js";
+import { cacheRoot, isOfflineMode, isDebugMode, getGitHubToken, engineDir, parseSearchPaths, makeBootstrapError, userMessageForBootstrapFailure, MAX_RETRIES, } from "./installer_env.js";
+// Re-export network operations
+export { sha256File, sleep, fetchWithRetry, download, releaseBaseUrl, readShaSums, readShaSumsFromUrl, discoverRelease, findAsset, downloadAsset, extractTarGz, makeExecutable, } from "./installer_network.js";
+import { sha256File, fetchWithRetry, download, releaseBaseUrl, readShaSums, readShaSumsFromUrl, discoverRelease, findAsset, downloadAsset, extractTarGz, makeExecutable, } from "./installer_network.js";
+// Re-export version management
+export { getCurrentVersion, setCurrentVersion, needsUpdate, checkUpdates, parseEngineVersionFromAsset, discoverLatestEnginesRelease, extractEngineVersionsFromRelease, checkRemoteUpdates, } from "./installer_version.js";
+import { getCurrentVersion, setCurrentVersion, discoverLatestEnginesRelease, extractEngineVersionsFromRelease, } from "./installer_version.js";
 // ============================================================
-// Configuration (P2-26: Environment variable support)
+// Main Installation Logic
 // ============================================================
-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)
-const MAX_RETRIES = getEnvInt("VIBECODE_MAX_RETRIES", 3);
-const RETRY_DELAY_MS = getEnvInt("VIBECODE_RETRY_DELAY_MS", 1000);
-const DOWNLOAD_TIMEOUT_MS = getEnvInt("VIBECODE_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);
-}
-function getGitHubToken() {
-    return process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim() || null;
-}
-function getAuthHeaders() {
-    const token = getGitHubToken();
-    const headers = {
-        "User-Agent": "vibecode-installer",
-    };
-    if (token) {
-        headers["Authorization"] = `token ${token}`;
-    }
-    return headers;
+/**
+ * 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;
+    });
 }
-// ============================================================
-// Cache Management
-// ============================================================
 /**
- * Get platform-appropriate cache root directory
+ * Ensure a single engine is installed and return its resolved binary path.
+ * Thread-safe via per-engine lock.
+ *
+ * This is the primitive used by JIT acquisition (P3).
  */
-export function cacheRoot() {
-    const override = (process.env.VIBECODE_CACHE ?? "").trim();
-    if (override) {
-        return path.resolve(override);
+export async function ensureEngine(name) {
+    const platform = detectPlatform();
+    const lockPath = path.join(cacheRoot(), "locks", `install_${platform}_${name}.lock`);
+    return await withLock(lockPath, async () => ensureOne(name, platform));
+}
+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;
     }
-    const home = os.homedir();
-    if (process.platform === "darwin") {
-        return path.join(home, "Library", "Caches", "vibecode");
+    // 2. Embedded binary (bundled in npm package) - for offline/air-gapped environments
+    const embeddedBin = await resolveEmbeddedBinary(name, platform);
+    if (embeddedBin) {
+        return embeddedBin;
     }
-    if (process.platform === "win32") {
-        return path.join(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "vibecode");
+    // 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;
+        let assetInfo;
+        const release = await discoverRelease(spec.repo, spec.version);
+        if (release) {
+            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) {
+                    // Use API URL for SHA file too (for private repos)
+                    const token = getGitHubToken();
+                    if (token) {
+                        const res = await fetchWithRetry(shaInfo.url, MAX_RETRIES, {
+                            "Accept": "application/octet-stream",
+                        });
+                        const text = await res.text();
+                        shaMap = new Map();
+                        for (const line of text.split("\n")) {
+                            const t = line.trim();
+                            if (!t)
+                                continue;
+                            const m = t.match(/^([a-fA-F0-9]{64})\s+(.+)$/);
+                            if (m)
+                                shaMap.set(m[2].trim(), m[1].toLowerCase());
+                        }
+                    }
+                    else {
+                        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()) {
+                logger.debug(`[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) - use API URL for private repos
+        if (assetInfo && getGitHubToken()) {
+            await downloadAsset(assetInfo, archivePath);
+        }
+        else {
+            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);
     }
-    // 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);
 }
+// ============================================================
+// External/Embedded Binary Resolution
+// ============================================================
 async function resolveExternalBinary(name, platform) {
     const spec = ENGINE_SPECS[name];
     const roots = parseSearchPaths(process.env.VIBECODE_BIN_PATH);
@@ -131,468 +220,53 @@ async function resolveExternalBinary(name, platform) {
 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) {
-    // Test/dev escape hatch: allow forcing offline failures even when the repo/package includes bundled binaries.
-    if ((process.env.VIBECODE_DISABLE_EMBEDDED_BINS ?? "").trim() === "1")
-        return null;
-    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);
-    // 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;
-}
-// ============================================================
-// 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, 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");
-}
-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: {
-                    ...getAuthHeaders(),
-                    "Accept": "application/vnd.github+json",
-                },
-            });
-            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: {
-                ...getAuthHeaders(),
-                "Accept": "application/vnd.github+json",
-            },
-        });
-        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);
-}
-/**
- * Download asset from GitHub release (supports private repos with GITHUB_TOKEN)
- */
-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);
-}
-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;
-}
-/**
- * Parse engine version from asset filename
- * Format: {prefix}_{version}_{platform}.tar.gz
- * Example: spec-high_1.0.0_linux_x64.tar.gz
- */
-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
- */
-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()) {
-                console.log(`[debug] Found latest engines release: ${enginesRelease.tag_name}`);
-            }
-            return enginesRelease;
-        }
-        return null;
-    }
-    catch (e) {
-        if (isDebugMode()) {
-            console.log(`[debug] Failed to discover latest release: ${e}`);
-        }
-        return null;
-    }
-}
-/**
- * Extract engine versions from release assets
- */
-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;
+    // 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 result;
+    return null;
 }
 /**
- * Update engines from remote release (ignoring registry.ts versions)
+ * Resolve embedded binary from bundled bin/ directory
  */
-export async function updateFromRemote(force = false) {
-    const platform = detectPlatform();
-    const repo = ENGINE_SPECS["spec-high"].repo;
-    const release = await discoverLatestEnginesRelease(repo);
-    const updated = [];
-    const failed = [];
-    if (!release) {
-        if (isDebugMode()) {
-            console.log("[debug] No remote release found");
+async function resolveEmbeddedBinary(name, platform) {
+    // Test/dev escape hatch: allow forcing offline failures even when the repo/package includes bundled binaries.
+    if ((process.env.VIBECODE_DISABLE_EMBEDDED_BINS ?? "").trim() === "1")
+        return null;
+    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;
         }
-        return { updated, failed };
     }
-    const remoteVersions = extractEngineVersionsFromRelease(release, platform);
-    for (const name of Object.keys(ENGINE_SPECS)) {
-        const remote = remoteVersions.get(name);
-        if (!remote)
-            continue;
-        const currentVersion = await getCurrentVersion(name);
-        const needsUpdate = force || currentVersion !== remote.version;
-        if (!needsUpdate)
-            continue;
-        try {
-            // Download and install from remote
-            await installEngineFromRelease(name, release, remote.version, platform);
-            updated.push(name);
-            if (isDebugMode()) {
-                console.log(`[debug] Updated ${name}: ${currentVersion} → ${remote.version}`);
-            }
-        }
-        catch (e) {
-            failed.push(name);
-            if (isDebugMode()) {
-                console.log(`[debug] Failed to update ${name}: ${e}`);
-            }
-        }
+    catch {
+        // ignore
     }
-    return { updated, failed };
+    return null;
 }
+// ============================================================
+// Install Engine from Release
+// ============================================================
 /**
  * Install a specific engine from a GitHub release
  */
@@ -674,6 +348,50 @@ async function installEngineFromRelease(name, release, version, platform) {
     return bin;
 }
 // ============================================================
+// Remote Update (uses installEngineFromRelease)
+// ============================================================
+/**
+ * Update engines from remote release (ignoring registry.ts versions)
+ */
+export async function updateFromRemote(force = false) {
+    const platform = detectPlatform();
+    const repo = ENGINE_SPECS["spec-high"].repo;
+    const release = await discoverLatestEnginesRelease(repo);
+    const updated = [];
+    const failed = [];
+    if (!release) {
+        if (isDebugMode()) {
+            logger.debug("[debug] No remote release found");
+        }
+        return { updated, failed };
+    }
+    const remoteVersions = extractEngineVersionsFromRelease(release, platform);
+    for (const name of Object.keys(ENGINE_SPECS)) {
+        const remote = remoteVersions.get(name);
+        if (!remote)
+            continue;
+        const currentVersion = await getCurrentVersion(name);
+        const needsUpdate = force || currentVersion !== remote.version;
+        if (!needsUpdate)
+            continue;
+        try {
+            // Download and install from remote
+            await installEngineFromRelease(name, release, remote.version, platform);
+            updated.push(name);
+            if (isDebugMode()) {
+                logger.debug(`[debug] Updated ${name}: ${currentVersion} → ${remote.version}`);
+            }
+        }
+        catch (e) {
+            failed.push(name);
+            if (isDebugMode()) {
+                logger.debug(`[debug] Failed to update ${name}: ${e}`);
+            }
+        }
+    }
+    return { updated, failed };
+}
+// ============================================================
 // Cache Validation
 // ============================================================
 /**
@@ -759,154 +477,6 @@ export async function clearAllCaches() {
     }
 }
 // ============================================================
-// 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;
-        let assetInfo;
-        const release = await discoverRelease(spec.repo, spec.version);
-        if (release) {
-            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) {
-                    // Use API URL for SHA file too (for private repos)
-                    const token = getGitHubToken();
-                    if (token) {
-                        const res = await fetchWithRetry(shaInfo.url, MAX_RETRIES, {
-                            "Accept": "application/octet-stream",
-                        });
-                        const text = await res.text();
-                        shaMap = new Map();
-                        for (const line of text.split("\n")) {
-                            const t = line.trim();
-                            if (!t)
-                                continue;
-                            const m = t.match(/^([a-fA-F0-9]{64})\s+(.+)$/);
-                            if (m)
-                                shaMap.set(m[2].trim(), m[1].toLowerCase());
-                        }
-                    }
-                    else {
-                        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) - use API URL for private repos
-        if (assetInfo && getGitHubToken()) {
-            await downloadAsset(assetInfo, archivePath);
-        }
-        else {
-            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) {