tanmi-dock 0.9.3 → 1.0.3

package/dist/core/codepac.js

@@ -7,7 +7,7 @@ import { promisify } from 'util';
 import path from 'path';
 import fs from 'fs/promises';
 import os from 'os';
-import { isPlatformDir, normalizePlatformValue, getBaseKeyForCodepac, collectRequestedPlatformTargets, } from './platform.js';
+import { isPlatformDir, normalizePlatformValue, getBaseKeyForCodepac, platformValueToKey, collectRequestedPlatformTargets, getRequestedPlatformTargets, resolveSparseConfig, } from './platform.js';
 import * as logger from '../utils/logger.js';
 const execAsync = promisify(exec);
 // 代理配置缓存
@@ -47,6 +47,8 @@ function getEnvWithProxy() {
  * codepac 命令名称
  */
 const CODEPAC_CMD = 'codepac';
+const GIT_CMD = 'git';
+const MIN_GIT_VERSION = '2.22.0';
 /**
  * 检查 codepac 是否已安装
  */
@@ -59,6 +61,67 @@ export async function isCodepacInstalled() {
         return false;
     }
 }
+export async function checkCodepacEnvironment() {
+    const commandProbe = await runShellProbe(`command -v ${CODEPAC_CMD}`);
+    logger.debug(`[codepac-env] CodePac 命令检测: command="${commandProbe.command}", ok=${commandProbe.ok}, stdout="${summarizeProbeText(commandProbe.stdout)}", stderr="${summarizeProbeText(commandProbe.stderr)}", error="${commandProbe.error ?? ''}"`);
+    const gitProbe = await runShellProbe(`${GIT_CMD} --version`);
+    const gitRaw = gitProbe.stdout.trim() || gitProbe.stderr.trim();
+    const gitVersion = extractVersion(gitRaw);
+    const gitOk = gitProbe.ok && !!gitVersion && compareVersions(gitVersion, MIN_GIT_VERSION) >= 0;
+    logger.debug(`[codepac-env] Git 版本检测: command="${gitProbe.command}", ok=${gitProbe.ok}, raw="${summarizeProbeText(gitRaw)}", parsed="${gitVersion ?? ''}", minimum="${MIN_GIT_VERSION}", pass=${gitOk}, error="${gitProbe.error ?? ''}"`);
+    const gitLfsVersion = await runShellProbe('git-lfs --version');
+    const gitLfsSubcommand = await runShellProbe(`${GIT_CMD} lfs --version`);
+    const gitLfsOk = gitLfsVersion.ok && gitLfsSubcommand.ok;
+    logger.debug(`[codepac-env] Git LFS 检测: git-lfs ok=${gitLfsVersion.ok}, stdout="${summarizeProbeText(gitLfsVersion.stdout)}", stderr="${summarizeProbeText(gitLfsVersion.stderr)}", error="${gitLfsVersion.error ?? ''}"; git lfs ok=${gitLfsSubcommand.ok}, stdout="${summarizeProbeText(gitLfsSubcommand.stdout)}", stderr="${summarizeProbeText(gitLfsSubcommand.stderr)}", error="${gitLfsSubcommand.error ?? ''}"`);
+    const versionProbe = await runShellProbe(`${CODEPAC_CMD} --version`);
+    const versionRaw = versionProbe.stdout.trim() || versionProbe.stderr.trim();
+    logger.debug(`[codepac-env] CodePac 版本检测: command="${versionProbe.command}", ok=${versionProbe.ok}, stdout="${summarizeProbeText(versionProbe.stdout)}", stderr="${summarizeProbeText(versionProbe.stderr)}", error="${versionProbe.error ?? ''}"`);
+    const codepacCommand = {
+        ok: commandProbe.ok,
+        command: commandProbe.command,
+        path: commandProbe.ok ? commandProbe.stdout.trim() : undefined,
+        message: commandProbe.ok ? `已找到: ${commandProbe.stdout.trim()}` : '未找到 codepac 命令',
+        error: commandProbe.error || commandProbe.stderr.trim() || undefined,
+    };
+    const git = {
+        ok: gitOk,
+        command: gitProbe.command,
+        minimumVersion: MIN_GIT_VERSION,
+        version: gitVersion ?? undefined,
+        raw: gitRaw || undefined,
+        message: gitOk
+            ? `${gitVersion} 可用`
+            : gitProbe.ok
+                ? `Git 版本需不低于 ${MIN_GIT_VERSION}${gitVersion ? `，当前 ${gitVersion}` : ''}`
+                : '无法执行 git --version',
+        error: gitProbe.error || gitProbe.stderr.trim() || undefined,
+    };
+    const gitLfs = {
+        ok: gitLfsOk,
+        commands: {
+            gitLfsVersion,
+            gitLfsSubcommand,
+        },
+        message: gitLfsOk ? '已安装' : 'Git LFS 不可用',
+    };
+    const codepacVersion = {
+        ok: versionProbe.ok,
+        command: versionProbe.command,
+        version: versionProbe.ok ? versionRaw : undefined,
+        raw: versionRaw || undefined,
+        message: versionProbe.ok ? versionRaw || '可执行' : 'codepac --version 执行失败',
+        error: versionProbe.error || versionProbe.stderr.trim() || undefined,
+    };
+    const result = {
+        ok: codepacCommand.ok && git.ok && gitLfs.ok && codepacVersion.ok,
+        codepacCommand,
+        git,
+        gitLfs,
+        codepacVersion,
+    };
+    logger.debug(`[codepac-env] 环境检测结果: ok=${result.ok}, codepac=${result.codepacCommand.ok}, git=${result.git.ok}, gitLfs=${result.gitLfs.ok}, version=${result.codepacVersion.ok}`);
+    return result;
+}
 /**
  * 获取 codepac 版本
  */
@@ -71,6 +134,57 @@ export async function getVersion() {
         return null;
     }
 }
+async function runShellProbe(command) {
+    try {
+        const output = await execAsync(command, { encoding: 'utf8' });
+        const { stdout, stderr } = normalizeExecOutput(output);
+        return { ok: true, command, stdout: stdout ?? '', stderr: stderr ?? '' };
+    }
+    catch (err) {
+        const execError = err;
+        return {
+            ok: false,
+            command,
+            stdout: execError.stdout ?? '',
+            stderr: execError.stderr ?? '',
+            error: execError.message,
+        };
+    }
+}
+function normalizeExecOutput(output) {
+    if (typeof output === 'string') {
+        return { stdout: output, stderr: '' };
+    }
+    if (output && typeof output === 'object') {
+        const value = output;
+        return {
+            stdout: typeof value.stdout === 'string' ? value.stdout : '',
+            stderr: typeof value.stderr === 'string' ? value.stderr : '',
+        };
+    }
+    return { stdout: '', stderr: '' };
+}
+function extractVersion(text) {
+    const match = text.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+}
+function compareVersions(left, right) {
+    const leftParts = left.split('.').map((part) => Number.parseInt(part, 10));
+    const rightParts = right.split('.').map((part) => Number.parseInt(part, 10));
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index++) {
+        const leftValue = leftParts[index] ?? 0;
+        const rightValue = rightParts[index] ?? 0;
+        if (leftValue > rightValue)
+            return 1;
+        if (leftValue < rightValue)
+            return -1;
+    }
+    return 0;
+}
+function summarizeProbeText(text) {
+    return text.replace(/\s+/g, ' ').trim().slice(0, 240);
+}
 /**
  * 使用 codepac 安装依赖
  */
@@ -242,11 +356,7 @@ function generateTempDirName() {
  * @deprecated installSingle 已被本函数替代
  */
 export async function downloadToTemp(options) {
-    const { url, commit, branch, libName, platforms, sparse, vars, onProgress, onHeartbeat, onTempDirCreated } = options;
-    // 检查 codepac 是否安装
-    if (!(await isCodepacInstalled())) {
-        throw new Error('codepac 未安装，请先安装 codepac 工具');
-    }
+    const { url, commit, branch, libName, platforms, sparse, vars, useGitLightweightDownload = true, onProgress, onHeartbeat, onTempDirCreated, } = options;
     // 创建唯一临时目录
     const tempDirName = generateTempDirName();
     const tempDir = path.join(os.tmpdir(), tempDirName);
@@ -278,58 +388,34 @@ export async function downloadToTemp(options) {
             tempConfig.vars = vars;
         }
         await fs.writeFile(configPath, JSON.stringify(tempConfig, null, 2), 'utf-8');
-        // 构建 codepac 命令参数
-        // 关键: codepac -p 需要基础 CLI key (mac/ios/android)
-        // 无论用户请求 macOS 还是 macOS-asan，都传 mac 给 codepac
-        // codepac 会下载所有变体，之后我们做清理
-        const baseKeys = [...new Set(platforms.map(getBaseKeyForCodepac))];
-        const args = ['install', '-cf', configPath, '-td', tempDir, '-p', ...baseKeys];
-        // 调用 codepac
-        await spawnCodepac(args, tempDir, onProgress, onHeartbeat);
-        // 分析下载结果，区分平台目录和共享文件
-        const entries = await fs.readdir(libDir, { withFileTypes: true });
-        const downloadedPlatforms = [];
-        const sharedFiles = [];
-        for (const entry of entries) {
-            const name = entry.name;
-            if (isPlatformDir(name)) {
-                // 标准化平台目录名（例如 "macos" -> "macOS"）
-                downloadedPlatforms.push(normalizePlatformValue(name));
-            }
-            else {
-                sharedFiles.push(name);
-            }
-        }
-        // 后处理：清理用户未请求的平台目录
-        // 例如用户只请求 macOS，但 codepac 下载了 macOS 和 macOS-asan
-        const requestedTargets = new Set(collectRequestedPlatformTargets(platforms, sparse, vars));
-        const platformDirs = [];
-        const cleanedPlatforms = [];
-        for (const platform of downloadedPlatforms) {
-            if (requestedTargets.has(platform)) {
-                // 请求平台直接命中，或通过 sparse 映射命中承载目录时保留
-                platformDirs.push(platform);
-            }
-            else {
-                // 用户未请求的平台，删除
-                const platformPath = path.join(libDir, platform);
+        const gitDownloaded = useGitLightweightDownload
+            ? await tryDownloadWithGit(options, tempDir, libDir).catch(async (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                onProgress?.(`Git 轻量下载失败，切换 codepac 下载: ${message}`);
                 try {
-                    await fs.rm(platformPath, { recursive: true, force: true });
-                    cleanedPlatforms.push(platform);
+                    await fs.rm(libDir, { recursive: true, force: true });
                 }
-                catch (err) {
-                    logger.warn(`清理平台目录 ${platform} 失败: ${err.message}`);
+                catch {
+                    // 忽略回退前的清理错误，后续 codepac 仍会在临时目录中重新下载。
                 }
+                return false;
+            })
+            : false;
+        if (!gitDownloaded) {
+            // 检查 codepac 是否安装
+            if (!(await isCodepacInstalled())) {
+                throw new Error('codepac 未安装，请先安装 codepac 工具');
             }
+            // 构建 codepac 命令参数
+            // 关键: codepac -p 需要基础 CLI key (mac/ios/android)
+            // 无论用户请求 macOS 还是 macOS-asan，都传 mac 给 codepac
+            // codepac 会下载所有变体，之后我们做清理
+            const baseKeys = [...new Set(platforms.map(getBaseKeyForCodepac))];
+            const args = ['install', '-cf', configPath, '-td', tempDir, '-p', ...baseKeys];
+            // 调用 codepac
+            await spawnCodepac(args, tempDir, onProgress, onHeartbeat);
         }
-        return {
-            tempDir,
-            libDir,
-            allPlatformDirs: downloadedPlatforms,
-            platformDirs,
-            sharedFiles,
-            cleanedPlatforms,
-        };
+        return analyzeDownloadedLibrary({ tempDir, libDir, platforms, sparse, vars });
     }
     catch (error) {
         // 清理临时目录
@@ -344,16 +430,463 @@ export async function downloadToTemp(options) {
         throw new Error(`下载库失败: ${message}`);
     }
 }
+async function tryDownloadWithGit(options, tempDir, libDir) {
+    const { url, commit, branch, platforms, sparse, vars, onProgress, onHeartbeat } = options;
+    if (platforms.length === 0 || !isCommitHash(commit)) {
+        return false;
+    }
+    const sparseConfig = resolveSparseConfig(sparse, vars);
+    if (sparse && !sparseConfig) {
+        return false;
+    }
+    onProgress?.('尝试使用 Git 轻量下载');
+    await spawnGit(['--version'], tempDir, onProgress, onHeartbeat);
+    await spawnGit(['lfs', 'version'], tempDir, onProgress, onHeartbeat);
+    await spawnGit([
+        'clone',
+        '--filter=blob:none',
+        '--depth',
+        '1',
+        '--single-branch',
+        '--no-checkout',
+        '--branch',
+        branch,
+        url,
+        libDir,
+    ], tempDir, onProgress, onHeartbeat, { GIT_LFS_SKIP_SMUDGE: '1' });
+    const partialCloneFilter = await spawnGit(['-C', libDir, 'config', '--get', 'remote.origin.partialclonefilter'], tempDir, undefined, onHeartbeat, undefined, false);
+    if (partialCloneFilter.stdout.trim() !== 'blob:none') {
+        throw new Error('远端未启用 blob:none 轻量克隆');
+    }
+    const sparseCheckoutPaths = sparseConfig
+        ? buildSparseCheckoutPaths(platforms, sparseConfig)
+        : await buildRepositorySparseCheckoutPaths(libDir, platforms, sparse, vars, tempDir, onHeartbeat);
+    if (sparseCheckoutPaths.length === 0) {
+        throw new Error('无法推导 Git sparse checkout 路径');
+    }
+    await spawnGit(['-C', libDir, 'sparse-checkout', 'init', '--no-cone'], tempDir, onProgress, onHeartbeat);
+    await spawnGit(['-C', libDir, 'sparse-checkout', 'set', '--no-cone', ...sparseCheckoutPaths], tempDir, onProgress, onHeartbeat);
+    try {
+        await checkoutGitCommit(libDir, commit, tempDir, onProgress, onHeartbeat);
+    }
+    catch {
+        await spawnGit(['-C', libDir, 'fetch', '--depth', '1', 'origin', commit], tempDir, onProgress, onHeartbeat, {
+            GIT_LFS_SKIP_SMUDGE: '1',
+        });
+        await checkoutGitCommit(libDir, commit, tempDir, onProgress, onHeartbeat);
+    }
+    const includePaths = sparseConfig
+        ? buildSparseGitLfsIncludePaths(platforms, sparseConfig)
+        : await buildGitLfsIncludePathsFromRepository(libDir, platforms, sparse, vars, tempDir, onHeartbeat);
+    const expectedLfsPaths = sparseConfig
+        ? await buildGitLfsFilePathsForIncludes(libDir, includePaths, tempDir, onHeartbeat)
+        : includePaths;
+    if (includePaths.length > 0) {
+        await spawnGit(['-C', libDir, 'lfs', 'pull', '--include', includePaths.join(','), '--exclude', ''], tempDir, onProgress, onHeartbeat);
+    }
+    await verifyGitDownloadResult({ libDir, platforms, sparse, vars, expectedLfsPaths });
+    await finalizeMinisizeGitDownload(libDir, tempDir, onProgress, onHeartbeat);
+    onProgress?.('Git 轻量下载完成');
+    return true;
+}
+function isCommitHash(commit) {
+    return /^[0-9a-f]{7,40}$/i.test(commit);
+}
+function buildSparseGitLfsIncludePaths(platforms, sparseConfig) {
+    return expandGitLfsIncludeRoots(buildSparseCheckoutPaths(platforms, sparseConfig));
+}
+function buildSparseCheckoutPaths(platforms, sparseConfig) {
+    const includeRoots = [];
+    const commonItems = sparseConfig.common;
+    if (Array.isArray(commonItems)) {
+        includeRoots.push(...commonItems.filter((item) => typeof item === 'string'));
+    }
+    for (const platform of platforms) {
+        const rawItems = getSparseItemsForPlatform(platform, sparseConfig);
+        if (Array.isArray(rawItems)) {
+            includeRoots.push(...rawItems.filter((item) => typeof item === 'string'));
+        }
+        else {
+            includeRoots.push(...getRequestedPlatformTargets(platform, sparseConfig));
+        }
+    }
+    return [...new Set(includeRoots.map((item) => normalizeGitPath(item)).filter((item) => Boolean(item)))];
+}
+function getSparseItemsForPlatform(platform, sparseConfig) {
+    const candidateKeys = [
+        platform,
+        platformValueToKey(platform),
+        normalizePlatformValue(platform),
+        getBaseKeyForCodepac(platform),
+    ];
+    for (const key of new Set(candidateKeys)) {
+        const items = sparseConfig[key];
+        if (Array.isArray(items)) {
+            return items;
+        }
+    }
+    return undefined;
+}
+async function buildGitLfsIncludePathsFromRepository(libDir, platforms, sparse, vars, cwd, onHeartbeat) {
+    const requestedTargets = new Set(collectRequestedPlatformTargets(platforms, sparse, vars));
+    const lfsPaths = await listGitLfsFilePaths(libDir, cwd, onHeartbeat);
+    const selectedPaths = lfsPaths.filter((line) => {
+        const [topLevel] = line.split('/');
+        if (!topLevel || !isPlatformDir(topLevel)) {
+            return true;
+        }
+        return requestedTargets.has(normalizePlatformValue(topLevel));
+    });
+    return [...new Set(selectedPaths)];
+}
+async function buildGitLfsFilePathsForIncludes(libDir, includePaths, cwd, onHeartbeat) {
+    const includeRoots = includePaths
+        .map((item) => normalizeGitPath(item.replace(/\/\*\*$/g, '')))
+        .filter((item) => Boolean(item));
+    const uniqueIncludeRoots = [...new Set(includeRoots)];
+    if (uniqueIncludeRoots.length === 0) {
+        return [];
+    }
+    const lfsPaths = await listGitLfsFilePaths(libDir, cwd, onHeartbeat);
+    return lfsPaths.filter((lfsPath) => uniqueIncludeRoots.some((root) => lfsPath === root || lfsPath.startsWith(`${root}/`)));
+}
+async function listGitLfsFilePaths(libDir, cwd, onHeartbeat) {
+    const result = await spawnGit(['-C', libDir, 'lfs', 'ls-files', '--all', '--name-only'], cwd, undefined, onHeartbeat, undefined, false);
+    return result.stdout
+        .split(/\r?\n/)
+        .map((line) => normalizeGitPath(line))
+        .filter((line) => Boolean(line));
+}
+async function buildRepositorySparseCheckoutPaths(libDir, platforms, sparse, vars, cwd, onHeartbeat) {
+    const requestedTargets = new Set(collectRequestedPlatformTargets(platforms, sparse, vars));
+    const result = await spawnGit(['-C', libDir, 'ls-tree', '--name-only', 'HEAD'], cwd, undefined, onHeartbeat, undefined, false);
+    const topLevelEntries = result.stdout
+        .split(/\r?\n/)
+        .map((line) => normalizeGitPath(line))
+        .filter((line) => Boolean(line));
+    const hasRequestedPlatform = topLevelEntries.some((entry) => (isPlatformDir(entry) && requestedTargets.has(normalizePlatformValue(entry))));
+    if (!hasRequestedPlatform) {
+        throw new Error('仓库顶层目录未包含请求平台');
+    }
+    const selectedEntries = topLevelEntries.filter((entry) => {
+        if (!isPlatformDir(entry)) {
+            return true;
+        }
+        return requestedTargets.has(normalizePlatformValue(entry));
+    });
+    return selectedEntries.flatMap((entry) => [entry, `${entry}/**`]);
+}
+function expandGitLfsIncludeRoots(paths) {
+    const result = [];
+    for (const rawPath of paths) {
+        const normalized = normalizeGitPath(rawPath);
+        if (!normalized)
+            continue;
+        result.push(normalized);
+        result.push(`${normalized}/**`);
+    }
+    return [...new Set(result)];
+}
+function normalizeGitPath(value) {
+    const normalized = value
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/^\.\//, '')
+        .replace(/\/+$/g, '');
+    if (!normalized || normalized === '.' || normalized.startsWith('/')) {
+        return null;
+    }
+    if (normalized.split('/').some((part) => part === '..')) {
+        return null;
+    }
+    return normalized;
+}
+async function checkoutGitCommit(libDir, commit, cwd, onProgress, onHeartbeat) {
+    await spawnGit(['-C', libDir, 'checkout', commit], cwd, onProgress, onHeartbeat, {
+        GIT_LFS_SKIP_SMUDGE: '1',
+    });
+}
+async function verifyGitDownloadResult(options) {
+    const { libDir, platforms, sparse, vars, expectedLfsPaths } = options;
+    const result = await inspectDownloadedLibrary(libDir);
+    const requestedTargets = new Set(collectRequestedPlatformTargets(platforms, sparse, vars));
+    const missingTargets = [...requestedTargets].filter((platform) => !result.downloadedPlatforms.includes(platform));
+    if (missingTargets.length > 0) {
+        throw new Error(`Git 下载结果缺少请求平台目录: ${missingTargets.join(', ')}`);
+    }
+    const unresolvedPointer = await findFirstUnresolvedLfsPointer(libDir, expectedLfsPaths);
+    if (unresolvedPointer) {
+        throw new Error(`Git LFS 文件未完成下载: ${unresolvedPointer}`);
+    }
+}
+async function finalizeMinisizeGitDownload(libDir, cwd, onProgress, onHeartbeat) {
+    const gitDir = await resolveGitDir(libDir);
+    if (!gitDir) {
+        onProgress?.('Git minisize 收尾跳过: 未发现 .git 目录');
+        return;
+    }
+    const gitLog = await spawnGit(['-C', libDir, 'log', '-1'], cwd, undefined, onHeartbeat, undefined, false);
+    const head = await spawnGit(['-C', libDir, 'rev-parse', 'HEAD'], cwd, undefined, onHeartbeat, undefined, false);
+    const commit = head.stdout.trim();
+    onProgress?.(`Git minisize 收尾: gitdir=${gitDir}`);
+    const cleanupSummary = await cleanupRepoAndSubmoduleGitPayloads(libDir);
+    onProgress?.(`Git minisize 收尾: 清理 .git/lfs 和 .git/objects，仓库数=${cleanupSummary.repoCount}, 目录数=${cleanupSummary.cleanedDirectoryCount}`);
+    if (cleanupSummary.submodulePaths.length > 0) {
+        onProgress?.(`Git minisize 收尾: 已处理 submodule=${cleanupSummary.submodulePaths.join(',')}`);
+    }
+    const repoName = path.basename(libDir);
+    const commitMessagePath = path.join(gitDir, 'commit_message');
+    const commitHashPath = path.join(gitDir, 'commit_hash');
+    await fs.writeFile(commitMessagePath, `=============== ${repoName} ===============\n${gitLog.stdout}`, 'utf-8');
+    await fs.writeFile(commitHashPath, commit, 'utf-8');
+    onProgress?.(`Git minisize 收尾完成: commit_hash=${commit.slice(0, 12)}, marker=${commitHashPath}`);
+}
+async function cleanupRepoAndSubmoduleGitPayloads(repoDir) {
+    let repoCount = 0;
+    let cleanedDirectoryCount = 0;
+    const rootCleaned = await cleanupGitPayload(repoDir);
+    repoCount += rootCleaned === null ? 0 : 1;
+    cleanedDirectoryCount += rootCleaned ?? 0;
+    const submodulePaths = await collectGitSubmodulePaths(repoDir);
+    for (const submodulePath of submodulePaths) {
+        const submoduleCleaned = await cleanupGitPayload(path.join(repoDir, submodulePath));
+        repoCount += submoduleCleaned === null ? 0 : 1;
+        cleanedDirectoryCount += submoduleCleaned ?? 0;
+    }
+    return { repoCount, cleanedDirectoryCount, submodulePaths };
+}
+async function cleanupGitPayload(repoDir) {
+    const gitDir = await resolveGitDir(repoDir);
+    if (!gitDir)
+        return null;
+    return (await cleanupGitPayloadDirectory(path.join(gitDir, 'lfs'))
+        + await cleanupGitPayloadDirectory(path.join(gitDir, 'objects')));
+}
+async function cleanupGitPayloadDirectory(payloadDir) {
+    let entries = [];
+    try {
+        const dirEntries = await fs.readdir(payloadDir, { withFileTypes: true });
+        entries = Array.isArray(dirEntries)
+            ? dirEntries
+            : [];
+    }
+    catch {
+        return 0;
+    }
+    let cleanedCount = 0;
+    for (const entry of entries) {
+        const name = typeof entry === 'string' ? entry : entry.name;
+        const isDirectory = typeof entry === 'string' ? true : entry.isDirectory?.() ?? false;
+        if (!isDirectory)
+            continue;
+        const entryPath = path.join(payloadDir, name);
+        await fs.rm(entryPath, { recursive: true, force: true });
+        await fs.mkdir(entryPath, { recursive: true });
+        cleanedCount++;
+    }
+    return cleanedCount;
+}
+async function resolveGitDir(repoDir) {
+    const gitPath = path.join(repoDir, '.git');
+    try {
+        const stat = await fs.stat(gitPath);
+        if (stat.isDirectory()) {
+            return gitPath;
+        }
+        if (!stat.isFile()) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    try {
+        const content = await fs.readFile(gitPath, 'utf-8');
+        if (typeof content !== 'string') {
+            return null;
+        }
+        const match = content.match(/^gitdir:\s*(.+)$/m);
+        if (!match) {
+            return null;
+        }
+        return path.resolve(repoDir, match[1].trim());
+    }
+    catch {
+        return null;
+    }
+}
+async function collectGitSubmodulePaths(repoDir) {
+    const gitmodulesPath = path.join(repoDir, '.gitmodules');
+    let content;
+    try {
+        content = await fs.readFile(gitmodulesPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    if (typeof content !== 'string') {
+        return [];
+    }
+    const paths = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const match = rawLine.trim().match(/^path\s*=\s*(.+)$/);
+        if (!match)
+            continue;
+        const submodulePath = normalizeGitPath(match[1]);
+        if (submodulePath) {
+            paths.push(submodulePath);
+        }
+    }
+    const nestedPaths = await Promise.all(paths.map(async (submodulePath) => {
+        const childPaths = await collectGitSubmodulePaths(path.join(repoDir, submodulePath));
+        return childPaths.map((childPath) => `${submodulePath}/${childPath}`);
+    }));
+    return [...new Set([...paths, ...nestedPaths.flat()])];
+}
+async function findFirstUnresolvedLfsPointer(libDir, relativePaths) {
+    for (const relativePath of relativePaths) {
+        const content = await readSmallTextFile(path.join(libDir, relativePath));
+        if (content?.startsWith('version https://git-lfs.github.com/spec/v1')) {
+            return relativePath;
+        }
+    }
+    return null;
+}
+async function readSmallTextFile(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        if (!stat.isFile() || stat.size > 1024) {
+            return null;
+        }
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+async function analyzeDownloadedLibrary(options) {
+    const { tempDir, libDir, platforms, sparse, vars } = options;
+    const { downloadedPlatforms, sharedFiles } = await inspectDownloadedLibrary(libDir);
+    // 后处理：清理用户未请求的平台目录
+    // 例如用户只请求 macOS，但 codepac 下载了 macOS 和 macOS-asan
+    const requestedTargets = new Set(collectRequestedPlatformTargets(platforms, sparse, vars));
+    const platformDirs = [];
+    const cleanedPlatforms = [];
+    for (const platform of downloadedPlatforms) {
+        if (requestedTargets.has(platform)) {
+            // 请求平台直接命中，或通过 sparse 映射命中承载目录时保留
+            platformDirs.push(platform);
+        }
+        else {
+            // 用户未请求的平台，删除
+            const platformPath = path.join(libDir, platform);
+            try {
+                await fs.rm(platformPath, { recursive: true, force: true });
+                cleanedPlatforms.push(platform);
+            }
+            catch (err) {
+                logger.warn(`清理平台目录 ${platform} 失败: ${err.message}`);
+            }
+        }
+    }
+    return {
+        tempDir,
+        libDir,
+        allPlatformDirs: downloadedPlatforms,
+        platformDirs,
+        sharedFiles,
+        cleanedPlatforms,
+    };
+}
+async function inspectDownloadedLibrary(libDir) {
+    let entries = [];
+    try {
+        const dirEntries = await fs.readdir(libDir, { withFileTypes: true });
+        entries = Array.isArray(dirEntries)
+            ? dirEntries
+            : [];
+    }
+    catch {
+        entries = [];
+    }
+    const downloadedPlatforms = [];
+    const sharedFiles = [];
+    for (const entry of entries) {
+        const name = typeof entry === 'string' ? entry : entry.name;
+        const isDirectory = typeof entry === 'string' ? false : entry.isDirectory();
+        if (isDirectory && isPlatformDir(name)) {
+            const platformPath = path.join(libDir, name);
+            const platformHasFiles = await directoryHasFiles(platformPath);
+            if (platformHasFiles) {
+                // 标准化平台目录名（例如 "macos" -> "macOS"）
+                downloadedPlatforms.push(normalizePlatformValue(name));
+            }
+            else {
+                sharedFiles.push(name);
+            }
+        }
+        else {
+            sharedFiles.push(name);
+        }
+    }
+    return { downloadedPlatforms, sharedFiles };
+}
+async function directoryHasFiles(dirPath, depth = 0) {
+    if (depth > 32) {
+        return true;
+    }
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const name = typeof entry === 'string' ? entry : entry.name;
+            if (name.startsWith('.'))
+                continue;
+            if (typeof entry === 'string')
+                return true;
+            if (typeof entry.isFile === 'function' && entry.isFile())
+                return true;
+            if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
+                return true;
+            if (entry.isDirectory() && await directoryHasFiles(path.join(dirPath, name), depth + 1)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+function spawnGit(args, cwd, onProgress, onHeartbeat, extraEnv, forwardStdout = true) {
+    return spawnCommand(GIT_CMD, args, cwd, {
+        onProgress,
+        onHeartbeat,
+        env: { ...getEnvWithProxy(), ...extraEnv },
+        forwardStdout,
+    });
+}
 /**
  * 内部辅助函数: 执行 codepac 命令
  */
 function spawnCodepac(args, cwd, onProgress, onHeartbeat) {
+    return spawnCommand(CODEPAC_CMD, args, cwd, {
+        onProgress,
+        onHeartbeat,
+        env: getEnvWithProxy(),
+    }).then(() => undefined);
+}
+function spawnCommand(command, args, cwd, options = {}) {
     return new Promise((resolve, reject) => {
-        const proc = spawn(CODEPAC_CMD, args, {
+        const proc = spawn(command, args, {
             cwd,
             stdio: 'pipe',
-            env: getEnvWithProxy(),
+            env: options.env ?? getEnvWithProxy(),
         });
+        if (!proc) {
+            reject(new Error(`无法执行 ${command} 命令`));
+            return;
+        }
+        let stdout = '';
         let stderr = '';
         const heartbeatIntervalMs = 10000;
         let heartbeatTimer = null;
@@ -364,11 +897,11 @@ function spawnCodepac(args, cwd, onProgress, onHeartbeat) {
             }
         };
         const resetHeartbeat = () => {
-            if (!onHeartbeat)
+            if (!options.onHeartbeat)
                 return;
             clearHeartbeat();
             heartbeatTimer = setTimeout(() => {
-                onHeartbeat('仍在处理中，可能在同步大文件，期间无新日志');
+                options.onHeartbeat?.('仍在处理中，可能在同步大文件，期间无新日志');
                 resetHeartbeat();
             }, heartbeatIntervalMs);
         };
@@ -376,9 +909,11 @@ function spawnCodepac(args, cwd, onProgress, onHeartbeat) {
         if (proc.stdout) {
             proc.stdout.on('data', (data) => {
                 resetHeartbeat();
-                const message = data.toString().trim();
-                if (message && onProgress) {
-                    onProgress(message);
+                const chunk = data.toString();
+                stdout += chunk;
+                const message = chunk.trim();
+                if (message && options.onProgress && options.forwardStdout !== false) {
+                    options.onProgress(message);
                 }
             });
         }
@@ -390,15 +925,15 @@ function spawnCodepac(args, cwd, onProgress, onHeartbeat) {
         }
         proc.on('error', (err) => {
             clearHeartbeat();
-            reject(new Error(`无法执行 codepac 命令: ${err.message}`));
+            reject(new Error(`无法执行 ${command} 命令: ${err.message}`));
         });
         proc.on('close', (code) => {
             clearHeartbeat();
             if (code === 0) {
-                resolve();
+                resolve({ stdout, stderr });
             }
             else {
-                const errorMsg = stderr.trim() || `codepac 命令执行失败，退出码: ${code}`;
+                const errorMsg = stderr.trim() || `${command} 命令执行失败，退出码: ${code}`;
                 reject(new Error(errorMsg));
             }
         });
@@ -406,6 +941,7 @@ function spawnCodepac(args, cwd, onProgress, onHeartbeat) {
 }
 export default {
     isCodepacInstalled,
+    checkCodepacEnvironment,
     getVersion,
     install,
     installSingle,