@lark-apaas/miaoda-cli 0.1.46 → 0.1.48

package/dist/services/app/migrate/run.js

@@ -0,0 +1,565 @@
+"use strict";
+/**
+ * 工程转换原语：在原工程目录内把工程转换（或修复）到目标 stack，并返回可验证的结构化结果。
+ *
+ * 流程（任一阶段失败即停止，保留当前目录现场，不自动回滚）：
+ *   preflight  严格读 meta、核对 app_id（沙箱内不一致则在写入 meta 时改写）、按磁盘布局识别源 stack、
+ *              选迁移 / 修复配置、检查符号链接
+ *   render     把目标模板渲染到临时模板目录（不复制用户工程；固定版本号进入结果）
+ *   precheck   在原目录只读预检规则冲突；有冲突 → 返回具体路径 / ID，工程未写入
+ *   apply      在原目录执行规则（遇冲突即停）
+ *   install    在原目录安装依赖（失败 = 转换失败，不软成功；manual 调用的退出码由 handler 放宽）
+ *   verify     按迁移配置在原目录执行验证命令；未配置则跳过（verify.status = not_configured）
+ *   restart    仅沙箱：清 vite cache、向在本目录运行的 dev 进程发重启信号（只是信号，不是健康结果）
+ *
+ * 冲突策略（conflictPolicy）按调用方区分，见 resolveConflictPolicy。precheck / apply 只对该策略下
+ * 仍是冲突的规则停止；按策略覆盖的用户内容列在 overwritten，保留未适配的进 warnings。
+ *
+ * apply 之后的任何失败都会留下部分转换的工程（originalIntact=false）。同目标重跑按磁盘真实
+ * 布局进入 repair，补齐适配后接续安装 / 构建；恢复原工程走调用方的代码版本能力。
+ * 执行期间的并发编辑由调用方现有互斥与调度保证，本原语不加锁。
+ *
+ * 平台 readiness（沙箱进程真正健康、预览可用）不在本原语内判定，由调用方（M04/M08）核验；
+ * 结果里明确标为 pending，不伪造。
+ *
+ * service 层：不产生终端输出，结果由 handler emit。
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATION_PURPOSES = void 0;
+exports.runMigration = runMigration;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const index_1 = require("../../../config/migrate-configs/index");
+const index_2 = require("../../../services/app/init/index");
+const migrate_rule_1 = require("../../../utils/migrate-rule");
+const spark_meta_1 = require("../../../utils/spark-meta");
+const project_snapshot_1 = require("../../../utils/project-snapshot");
+const engineering_state_1 = require("../../../utils/engineering-state");
+const run_npm_1 = require("../../../utils/run-npm");
+const error_1 = require("../../../utils/error");
+const logger_1 = require("../../../utils/logger");
+const detect_1 = require("./detect");
+const restart_1 = require("./restart");
+const symlinks_1 = require("./symlinks");
+/** 调用目的：用于记录与关联，并决定冲突策略（resolveConflictPolicy）；不据此重新判灰度 */
+exports.MIGRATION_PURPOSES = ['manual', 'upgrade', 'history_restore'];
+/**
+ * 冲突策略按调用方区分：
+ *   - upgrade / history_restore（平台调用）→ stop：平台迁移按结构化结果决定后续流程，冲突时保持
+ *     工程原样交给平台处理，转换本身不替用户丢内容。
+ *   - manual（feida-ai 升级全栈、本机手动执行）跨 stack 转换 → overwrite：调用方没有处理冲突的
+ *     环节，停下来会让应用卡在"类型已切、代码未转"的中间态；工程在 git 下，被替换的用户改动
+ *     可从历史找回，结果里逐条列出。
+ *   - manual 且磁盘已是目标布局（repair）→ keep：不同之处是用户在已转换工程上的改动，不能当成
+ *     旧布局残留覆盖；也不能停，否则调用方对已转换工程的重入（安装失败后重试等）会失败。
+ */
+function resolveConflictPolicy(purpose, mode) {
+    if (purpose !== 'manual')
+        return 'stop';
+    return mode === 'migrate' ? 'overwrite' : 'keep';
+}
+const DEFAULT_STEP_TIMEOUT_MS = 20 * 60 * 1000;
+/** template package.json 里专属于具体应用的字段，不参与 merge（避免覆盖用户值） */
+const USER_OWNED_PKG_FIELDS = [
+    'name',
+    'version',
+    'private',
+    'description',
+    'author',
+    'keywords',
+    'license',
+    'repository',
+    'homepage',
+    'bugs',
+];
+function stripUserOwnedFields(pkgPath) {
+    if (!node_fs_1.default.existsSync(pkgPath))
+        return;
+    const json = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
+    let changed = false;
+    for (const key of USER_OWNED_PKG_FIELDS) {
+        if (Reflect.deleteProperty(json, key))
+            changed = true;
+    }
+    if (changed)
+        node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(json, null, 2) + '\n');
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isTimeout(err) {
+    return /signal SIG(TERM|KILL)/.test(errMessage(err));
+}
+function newRunId() {
+    return `${Date.now().toString(36)}-${node_crypto_1.default.randomBytes(3).toString('hex')}`;
+}
+function flattenConflicts(results) {
+    return results.flatMap((r) => (r.action === 'conflict' ? (r.conflicts ?? []) : []));
+}
+function resolveSource(opts) {
+    const meta = (0, spark_meta_1.readSparkMetaStrict)(opts.targetDir);
+    let rewriteAppId;
+    if (opts.appId !== undefined &&
+        opts.appId !== '' &&
+        meta?.app_id !== undefined &&
+        meta.app_id !== opts.appId) {
+        // 沙箱里的工程就是当前应用的代码：不一致只会来自复制（本机 `+init` 写进 meta 的源应用
+        // app_id 随代码进了副本），拒绝会让副本永远迁移不了。本机目录可能放错，仍拒绝。
+        if (opts.sandbox) {
+            rewriteAppId = { from: meta.app_id, to: opts.appId };
+        }
+        else {
+            throw new error_1.AppError('MIGRATE_APP_ID_MISMATCH', `app_id '${opts.appId}' does not match .spark/meta.json app_id '${meta.app_id}'`, { next_actions: ['确认在正确的应用工程目录执行，或修正 --app-id / MIAODA_APP_ID'] });
+        }
+    }
+    const metaStack = meta?.stack !== undefined && meta.stack !== '' ? meta.stack : undefined;
+    const detectedStack = (0, detect_1.detectDiskStack)(opts.targetDir);
+    if (opts.from !== undefined &&
+        detectedStack !== 'unknown' &&
+        detectedStack !== opts.from &&
+        detectedStack !== opts.to) {
+        throw new error_1.AppError('MIGRATE_FROM_MISMATCH', `--from '${opts.from}' but project layout on disk is '${detectedStack}'`, { next_actions: ['省略 --from，按磁盘实际布局转换'] });
+    }
+    const from = detectedStack !== 'unknown' ? detectedStack : (opts.from ?? metaStack);
+    if (from === undefined) {
+        throw new error_1.AppError('MIGRATE_META_INCOMPLETE', 'cannot determine source stack: .spark/meta.json missing stack and layout not recognized', { next_actions: ['先执行 `miaoda app init`，或用 --from 指明源 stack'] });
+    }
+    if (opts.from !== undefined &&
+        detectedStack === 'unknown' &&
+        metaStack !== undefined &&
+        opts.from !== metaStack) {
+        throw new error_1.AppError('MIGRATE_FROM_MISMATCH', `--from '${opts.from}' but current stack is '${metaStack}'`, { next_actions: ['省略 --from 让 cli 自动读 meta.json，或确认 user app 状态'] });
+    }
+    const mode = from === opts.to ? 'repair' : 'migrate';
+    const config = mode === 'repair' ? (0, index_1.getRepairConfig)(opts.to) : (0, index_1.getMigrateConfig)(from, opts.to);
+    if (config === null) {
+        const supported = (0, index_1.listSupportedMigrations)()
+            .map((m) => `${m.from} → ${m.to}`)
+            .join(', ');
+        throw new error_1.AppError('MIGRATE_PATH_NOT_SUPPORTED', `no migrate config for '${from}' → '${opts.to}'`, { next_actions: [`已支持：${supported || '(none)'}`] });
+    }
+    return { metaStack, detectedStack, from, mode, config, rewriteAppId };
+}
+/**
+ * 执行一次原地工程转换。参数 / 绑定 / 路径类错误在任何副作用之前抛 AppError；
+ * 其余失败以 status=failed|conflict 的结果返回（工程是否被写入见 originalIntact）。
+ */
+function runMigration(opts) {
+    const targetDir = node_path_1.default.resolve(opts.targetDir);
+    const source = resolveSource({ ...opts, targetDir });
+    const runId = newRunId();
+    const stepTimeout = opts.stepTimeoutMs ??
+        (Number(process.env.MIAODA_MIGRATE_STEP_TIMEOUT_MS) || DEFAULT_STEP_TIMEOUT_MS);
+    const npmStdio = opts.quietStdout ? ['ignore', 2, 'inherit'] : 'inherit';
+    const conflictPolicy = resolveConflictPolicy(opts.purpose, source.mode);
+    const outcome = {
+        status: 'failed',
+        mode: source.mode,
+        runId,
+        purpose: opts.purpose,
+        conflictPolicy,
+        operationRef: opts.operationRef,
+        source: {
+            metaStack: source.metaStack,
+            detectedStack: source.detectedStack,
+            stack: source.from,
+        },
+        target: { stack: opts.to, cliVersion: opts.cliVersion },
+        stages: [
+            {
+                name: 'preflight',
+                status: 'ok',
+                durationMs: 0,
+                detail: `mode=${source.mode}, conflictPolicy=${conflictPolicy}`,
+            },
+        ],
+        conflicts: [],
+        overwritten: [],
+        warnings: [],
+        changes: { added: [], modified: [], deleted: [] },
+        results: [],
+        followLatestPackages: source.config.followLatestPackages ?? [],
+        install: { status: 'not_run' },
+        verify: {
+            status: source.config.verify === undefined ? 'not_configured' : 'not_run',
+            steps: [],
+        },
+        originalIntact: true,
+        restartSignalSent: false,
+        readiness: {
+            status: 'not_applicable',
+            detail: 'conversion did not complete; runtime not touched',
+        },
+    };
+    const statePaths = [
+        '.spark/local/.gitignore',
+        '.spark/local/engineering-state.json',
+        `.spark/local/engineering-state.json.${process.pid.toString()}.tmp`,
+    ];
+    const record = (status, stage, extra) => {
+        try {
+            const conflicts = (0, symlinks_1.writePathSymlinkConflicts)(targetDir, statePaths);
+            if (conflicts.length > 0) {
+                outcome.warnings.push(...conflicts.map((conflict) => ({
+                    path: conflict.path,
+                    code: 'MIGRATE_STATE_UNSAFE_SYMLINK',
+                    message: 'engineering state not written: unsafe symlink',
+                })));
+                return;
+            }
+            (0, engineering_state_1.writeEngineeringState)(targetDir, {
+                operation: 'migrate',
+                status,
+                stage,
+                runId,
+                code: extra?.code,
+                message: extra?.message,
+                fromStack: source.from,
+                toStack: opts.to,
+                templateVersion: outcome.target.templateVersion,
+                purpose: opts.purpose,
+                operationRef: opts.operationRef,
+            });
+        }
+        catch (err) {
+            outcome.warnings.push({
+                path: node_path_1.default.join(targetDir, '.spark/local'),
+                code: err.code,
+                message: `failed to record engineering state: ${errMessage(err)}`,
+            });
+            (0, logger_1.log)('migrate', `⚠ failed to record engineering state: ${errMessage(err)}`);
+        }
+    };
+    const stage = (name, fn) => {
+        const start = Date.now();
+        try {
+            const value = fn();
+            if (outcome.failure?.stage !== name) {
+                outcome.stages.push({ name, status: 'ok', durationMs: Date.now() - start });
+            }
+            return value;
+        }
+        catch (err) {
+            outcome.stages.push({
+                name,
+                status: 'failed',
+                durationMs: Date.now() - start,
+                detail: errMessage(err),
+            });
+            throw err;
+        }
+    };
+    // 进入 apply 后记录已写入工程的变更；快照失败只影响诊断，不影响结果判定
+    let before;
+    const captureChanges = () => {
+        if (before === undefined)
+            return;
+        try {
+            outcome.changes = (0, project_snapshot_1.diffSnapshots)(before, (0, project_snapshot_1.snapshotTree)(targetDir));
+        }
+        catch (err) {
+            outcome.warnings.push({
+                path: targetDir,
+                code: err.code,
+                message: `failed to list written changes: ${errMessage(err)}`,
+            });
+        }
+    };
+    const fail = (name, code, err, retryable) => {
+        outcome.status = 'failed';
+        outcome.failure = {
+            stage: name,
+            code,
+            message: errMessage(err),
+            retryable,
+            ...(isTimeout(err) ? { timedOut: true } : {}),
+        };
+        captureChanges();
+        record('failed', name, { code, message: outcome.failure.message });
+        return outcome;
+    };
+    const conflict = (name, code, conflicts) => {
+        outcome.status = 'conflict';
+        outcome.conflicts = conflicts;
+        outcome.failure = {
+            stage: name,
+            code,
+            message: conflicts.map((c) => `${c.path}: ${c.reason}`).join('; '),
+            retryable: false,
+        };
+        captureChanges();
+        if (name !== 'preflight') {
+            record('conflict', name, { code, message: outcome.failure.message });
+        }
+        return outcome;
+    };
+    const writePaths = [...(0, symlinks_1.migrationWritePaths)(source.config.rules, source.mode), ...statePaths];
+    const rejectSymlinks = (name, root, paths = writePaths, installed = false) => {
+        let conflicts;
+        try {
+            conflicts = (0, symlinks_1.migrationSymlinkConflicts)(root, paths, installed);
+        }
+        catch (err) {
+            outcome.stages.push({ name, status: 'failed', durationMs: 0, detail: errMessage(err) });
+            fail(name, 'MIGRATE_SYMLINK_CHECK_FAILED', err, true);
+            return true;
+        }
+        if (conflicts.length === 0)
+            return false;
+        const message = conflicts.map((c) => `${c.path}: ${c.reason}`).join('; ');
+        outcome.stages.push({ name, status: 'conflict', durationMs: 0, detail: message });
+        conflict(name, 'MIGRATE_UNSAFE_SYMLINK', conflicts);
+        return true;
+    };
+    const hasFailure = () => outcome.failure !== undefined;
+    if (rejectSymlinks('preflight', targetDir))
+        return outcome;
+    record('running', 'preflight');
+    (0, logger_1.log)('migrate', `run ${runId}: ${source.from} → ${opts.to} (mode=${source.mode}, purpose=${opts.purpose}, conflictPolicy=${conflictPolicy})`);
+    // 临时目录只放渲染后的目标模板；用户工程始终在原目录处理
+    const tmpRoot = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), `miaoda-migrate-${runId}-`));
+    const templateDir = node_path_1.default.join(tmpRoot, 'template');
+    try {
+        // ---- render ----
+        try {
+            stage('render', () => {
+                const tpl = (0, index_2.renderTemplate)({
+                    stack: opts.to,
+                    targetDir: templateDir,
+                    projectName: node_path_1.default.basename(targetDir),
+                });
+                outcome.target.templatePackage = tpl.packageName;
+                outcome.target.templateVersion = tpl.version;
+                outcome.target.archType = tpl.archType;
+                if (rejectSymlinks('render', templateDir))
+                    return;
+                stripUserOwnedFields(node_path_1.default.join(templateDir, 'package.json'));
+            });
+        }
+        catch (err) {
+            return fail('render', 'MIGRATE_TEMPLATE_UNAVAILABLE', err, true);
+        }
+        if (hasFailure())
+            return outcome;
+        // ---- precheck：只读预检，任何可识别冲突都在写入前返回 ----
+        const ruleOpts = {
+            sourceRoot: templateDir,
+            targetDir,
+            logPrefix: 'migrate',
+            mode: source.mode,
+            conflictPolicy,
+        };
+        try {
+            outcome.results = stage('precheck', () => (0, migrate_rule_1.applyMigrateRules)(source.config.rules, { ...ruleOpts, dryRun: true }));
+        }
+        catch (err) {
+            return fail('precheck', 'MIGRATE_RULE_FAILED', err, false);
+        }
+        const planned = flattenConflicts(outcome.results);
+        if (planned.length > 0) {
+            markLastStage(outcome, 'conflict', `${planned.length.toString()} conflict(s)`);
+            return conflict('precheck', 'MIGRATE_CONFLICT', planned);
+        }
+        // ---- apply：从这里开始写入原工程 ----
+        try {
+            before = (0, project_snapshot_1.snapshotTree)(targetDir);
+        }
+        catch (err) {
+            outcome.stages.push({ name: 'apply', status: 'failed', durationMs: 0 });
+            return fail('apply', 'MIGRATE_RULE_FAILED', err, true);
+        }
+        outcome.originalIntact = false;
+        try {
+            outcome.results = stage('apply', () => (0, migrate_rule_1.applyMigrateRules)(source.config.rules, { ...ruleOpts, stopOnConflict: true }));
+        }
+        catch (err) {
+            return fail('apply', 'MIGRATE_RULE_FAILED', err, false);
+        }
+        collectPolicyResults(outcome);
+        const late = flattenConflicts(outcome.results);
+        if (late.length > 0) {
+            // 依赖前序规则写入结果的冲突只在实际执行时出现：已停止，后续规则未执行
+            markLastStage(outcome, 'conflict', `${late.length.toString()} conflict(s)`);
+            return conflict('apply', 'MIGRATE_CONFLICT', late);
+        }
+        // 规则搬迁后的链接也必须仍在工程内，安装 / 构建才不会越界
+        if (rejectSymlinks('install', targetDir))
+            return outcome;
+        (0, spark_meta_1.writeSparkMeta)(targetDir, {
+            archType: outcome.target.archType,
+            version: outcome.target.templateVersion,
+            app_id: source.rewriteAppId?.to,
+        });
+        if (source.rewriteAppId !== undefined) {
+            outcome.warnings.push({
+                path: '.spark/meta.json',
+                code: 'MIGRATE_APP_ID_REWRITTEN',
+                message: `meta app_id '${source.rewriteAppId.from}' rewritten to current app '${source.rewriteAppId.to}' (copied project)`,
+            });
+            (0, logger_1.log)('migrate', `⚠ .spark/meta.json app_id '${source.rewriteAppId.from}' → '${source.rewriteAppId.to}'（复制来的工程）`);
+        }
+        // ---- install ----
+        const installArgs = [
+            'install',
+            '--no-audit',
+            '--no-fund',
+            '--registry',
+            (0, index_2.resolveNpmInstallRegistry)(),
+        ];
+        try {
+            stage('install', () => {
+                // 跨 stack 转换后依赖集合已变（lockfile 已由规则删除）：旧依赖树留着会与新 spec 撞 peer。
+                // repair 保留现有 node_modules，从上次中断处接续安装
+                if (source.mode === 'migrate') {
+                    node_fs_1.default.rmSync(node_path_1.default.join(targetDir, 'node_modules'), RM_WITH_RETRY);
+                }
+                if (outcome.followLatestPackages.length > 0) {
+                    const upgradeArgs = [
+                        ...installArgs,
+                        ...outcome.followLatestPackages.map((pkg) => `${pkg}@latest`),
+                    ];
+                    (0, logger_1.log)('migrate', `Running npm ${upgradeArgs.join(' ')}...`);
+                    (0, run_npm_1.execNpmSync)(upgradeArgs, { cwd: targetDir, stdio: npmStdio, timeout: stepTimeout });
+                    if (rejectSymlinks('install', targetDir, writePaths, true))
+                        return;
+                }
+                (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
+                (0, run_npm_1.execNpmSync)(installArgs, { cwd: targetDir, stdio: npmStdio, timeout: stepTimeout });
+            });
+            if (hasFailure())
+                return outcome;
+            outcome.install = { status: 'ok' };
+        }
+        catch (err) {
+            outcome.install = { status: 'failed', error: errMessage(err) };
+            return fail('install', 'MIGRATE_INSTALL_FAILED', err, true);
+        }
+        // ---- verify ----
+        if (rejectSymlinks('verify', targetDir, writePaths, true))
+            return outcome;
+        if (source.config.verify !== undefined) {
+            try {
+                stage('verify', () => {
+                    for (const step of source.config.verify ?? []) {
+                        const command = `npm ${step.join(' ')}`;
+                        (0, logger_1.log)('migrate', `Verifying: ${command}...`);
+                        try {
+                            (0, run_npm_1.execNpmSync)(step, { cwd: targetDir, stdio: npmStdio, timeout: stepTimeout });
+                            outcome.verify.steps.push({ command, status: 'ok' });
+                        }
+                        catch (err) {
+                            outcome.verify.steps.push({ command, status: 'failed', error: errMessage(err) });
+                            throw err;
+                        }
+                    }
+                });
+                outcome.verify.status = 'ok';
+            }
+            catch (err) {
+                outcome.verify.status = 'failed';
+                return fail('verify', 'MIGRATE_VERIFY_FAILED', err, true);
+            }
+        }
+        captureChanges();
+    }
+    finally {
+        try {
+            node_fs_1.default.rmSync(tmpRoot, { recursive: true, force: true });
+        }
+        catch (err) {
+            outcome.warnings.push({
+                path: tmpRoot,
+                code: err.code,
+                message: errMessage(err),
+            });
+            (0, logger_1.log)('migrate', `⚠ cleanup failed for ${tmpRoot}: ${errMessage(err)}`);
+        }
+    }
+    // ---- restart (sandbox only) ----
+    const restartStart = Date.now();
+    if (opts.sandbox) {
+        clearViteCache(targetDir);
+        outcome.restartSignalSent = (0, restart_1.signalDevRestart)(targetDir).length > 0;
+        outcome.stages.push({
+            name: 'restart',
+            status: 'ok',
+            durationMs: Date.now() - restartStart,
+            detail: outcome.restartSignalSent
+                ? 'restart signal sent'
+                : 'no dev process running in this directory',
+        });
+        outcome.readiness = {
+            status: 'pending_caller_verification',
+            detail: 'files and dependencies ready; sandbox process health / preview readiness must be verified by the caller',
+        };
+    }
+    else {
+        outcome.stages.push({
+            name: 'restart',
+            status: 'skipped',
+            durationMs: 0,
+            detail: 'local run: restart the dev process manually',
+        });
+        outcome.readiness = {
+            status: 'pending_caller_verification',
+            detail: 'local project converted; start `npm run dev` and verify the preview',
+        };
+    }
+    outcome.status = 'converted';
+    record('succeeded', opts.sandbox ? 'restart' : 'verify');
+    return outcome;
+}
+/** 汇总按冲突策略覆盖 / 保留的位置：覆盖的进 overwritten，保留未适配的作为 warning 交给调用方 */
+function collectPolicyResults(outcome) {
+    for (const r of outcome.results) {
+        outcome.overwritten.push(...(r.overwritten ?? []));
+        for (const c of r.kept ?? []) {
+            const ref = [
+                c.with === undefined ? '' : ` with ${c.with}`,
+                c.id === undefined ? '' : ` id=${c.id}`,
+            ];
+            outcome.warnings.push({
+                path: c.path,
+                code: 'MIGRATE_CONFLICT_KEPT',
+                message: `${c.reason}${ref.join('')}`,
+            });
+        }
+    }
+}
+function markLastStage(outcome, status, detail) {
+    const last = outcome.stages[outcome.stages.length - 1];
+    last.status = status;
+    last.detail = detail;
+}
+/**
+ * 删依赖目录时的重试：沙箱里 dev 进程（vite 依赖预构建写 node_modules/.vite）可能与删除并发，
+ * 递归删到父目录时子项刚被写入 → ENOTEMPTY。Node 对 ENOTEMPTY / EBUSY / EPERM 等按线性退避
+ * 重试（retryDelay × 第 n 次），6 次合计约 10s。并发写入方不停时仍会失败，由调用方先停 dev。
+ */
+const RM_WITH_RETRY = {
+    recursive: true,
+    force: true,
+    maxRetries: 6,
+    retryDelay: 500,
+};
+/**
+ * 清 vite 预构建缓存：依赖与 lockfile 变化后，旧 .vite/deps 的 lockfileHash 与新 lockfile
+ * 不一致，新 vite 冷启动时会中途 re-optimize，期间浏览器请求旧 hash 触发
+ * ERR_OUTDATED_OPTIMIZED_DEP → 504（见 fullstack-plugin#1143）。软失败。
+ */
+function clearViteCache(targetDir) {
+    const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
+    if (!node_fs_1.default.existsSync(viteCacheDir))
+        return;
+    try {
+        node_fs_1.default.rmSync(viteCacheDir, RM_WITH_RETRY);
+    }
+    catch (err) {
+        (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${errMessage(err)}`);
+    }
+}