@lark-apaas/miaoda-cli 0.1.46 → 0.1.48

package/dist/utils/migrate-rule.js

@@ -11,7 +11,26 @@ const node_path_1 = __importDefault(require("node:path"));
 const sync_rule_1 = require("./sync-rule");
 const spark_meta_1 = require("./spark-meta");
 const codemod_client_toolkit_lite_1 = require("./codemod-client-toolkit-lite");
+const migrate_adapters_1 = require("./migrate-adapters");
 const logger_1 = require("./logger");
+const TYPE_MISMATCH = 'file/directory type mismatch';
+/** 可能返回 conflict 的规则类型；dryRun 只评估这些规则 */
+const CONFLICT_CAPABLE_RULES = new Set([
+    'move-directory',
+    'move-file',
+    'move-capabilities',
+    'ensure-scripts',
+    'adapt-tsconfig',
+    'adapt-html-entry',
+    'adapt-nest-app-module',
+    'remove-known-default',
+    'carry-eslint-ignores',
+    'codemod-vite-config-fullstack',
+]);
+/** dryRun 下规则通过冲突判定、本应写入时的结果（未写盘） */
+function planned(rule, rel) {
+    return { rule, action: 'skipped', path: rel, detail: 'dry-run: no conflict' };
+}
 /**
  * 顺序执行 MigrateRule[]：
  *   - move-* / set-stack 是 migrate 专有 rule，本模块直接处理。
@@ -19,41 +38,83 @@ const logger_1 = require("./logger");
  *     applySyncRules —— 单条调用，逻辑跟 sync 完全对齐，避免行为漂移。
  *
  * 一条 rule 报错不影响后续（applySyncRules 内部已有 try/catch；本模块的 applyMove / applySetStack
- * 当前不 catch —— 如果 move 失败说明状态已经被破坏，应当直接抛错让 handler 决定回滚或上报）。
+ * 当前不 catch —— 如果 move 失败说明状态已经被破坏，应当直接抛错让调用方上报）。
  */
 function applyMigrateRules(rules, opts) {
     const results = [];
     for (const rule of rules) {
-        if (rule.type === 'move-directory' || rule.type === 'move-file') {
-            results.push(applyMove(rule, opts));
-            continue;
-        }
-        if (rule.type === 'set-stack') {
-            results.push(applySetStack(rule, opts));
+        if (opts.mode === 'repair' && rule.migrateOnly === true) {
+            results.push({ rule, action: 'skipped', detail: 'migrate-only rule skipped in repair mode' });
             continue;
         }
-        if (rule.type === 'delete-json-keys') {
-            results.push(applyDeleteJsonKeys(rule, opts));
+        if (opts.dryRun === true && !CONFLICT_CAPABLE_RULES.has(rule.type)) {
+            results.push({ rule, action: 'skipped', detail: 'dry-run: rule cannot conflict' });
             continue;
         }
-        if (rule.type === 'codemod-client-toolkit-lite') {
-            results.push(applyCodemodLite(rule, opts));
-            continue;
+        let result = applyOne(rule, opts);
+        if (result.action === 'conflict' && opts.conflictPolicy === 'keep') {
+            // 冲突规则在判定冲突前不写盘，整条跳过即保持用户内容原样
+            result = {
+                rule,
+                action: 'skipped',
+                path: result.path,
+                detail: 'conflict kept as-is',
+                kept: result.conflicts,
+            };
         }
-        if (rule.type === 'codemod-vite-config-fullstack') {
-            results.push(applyCodemodViteConfigFullstack(rule, opts));
-            continue;
-        }
-        if (rule.type === 'add-deps-from-template') {
-            results.push(applyAddDepsFromTemplate(rule, opts));
-            continue;
-        }
-        // 前面 if 已经把 migrate 专用 rule 都 narrow 掉，剩下的必然是 SyncRule
-        const [syncResult] = (0, sync_rule_1.applySyncRules)([rule], opts);
-        results.push(syncResult);
+        results.push(result);
+        if (opts.stopOnConflict === true && result.action === 'conflict')
+            break;
     }
     return results;
 }
+function applyOne(rule, opts) {
+    if (rule.type === 'move-capabilities') {
+        return applyMoveCapabilities(rule, opts);
+    }
+    if (rule.type === 'ensure-scripts') {
+        return applyEnsureScripts(rule, opts);
+    }
+    if (rule.type === 'adapt-tsconfig') {
+        return applyAdaptTsconfig(rule, opts);
+    }
+    if (rule.type === 'adapt-html-entry') {
+        return applyAdaptHtmlEntry(rule, opts);
+    }
+    if (rule.type === 'adapt-nest-app-module') {
+        return applyAdaptNestAppModule(rule, opts);
+    }
+    if (rule.type === 'remove-known-default') {
+        return applyRemoveKnownDefault(rule, opts);
+    }
+    if (rule.type === 'carry-eslint-ignores') {
+        return applyCarryEslintIgnores(rule, opts);
+    }
+    if (rule.type === 'relax-eslint-rules') {
+        return applyRelaxEslintRules(rule, opts);
+    }
+    if (rule.type === 'move-directory' || rule.type === 'move-file') {
+        return applyMove(rule, opts);
+    }
+    if (rule.type === 'set-stack') {
+        return applySetStack(rule, opts);
+    }
+    if (rule.type === 'delete-json-keys') {
+        return applyDeleteJsonKeys(rule, opts);
+    }
+    if (rule.type === 'codemod-client-toolkit-lite') {
+        return applyCodemodLite(rule, opts);
+    }
+    if (rule.type === 'codemod-vite-config-fullstack') {
+        return applyCodemodViteConfigFullstack(rule, opts);
+    }
+    if (rule.type === 'add-deps-from-template') {
+        return applyAddDepsFromTemplate(rule, opts);
+    }
+    // 前面 if 已经把 migrate 专用 rule 都 narrow 掉，剩下的必然是 SyncRule
+    const [syncResult] = (0, sync_rule_1.applySyncRules)([rule], opts);
+    return syncResult;
+}
 function applyMove(rule, opts) {
     const logPrefix = opts.logPrefix ?? 'migrate';
     const src = node_path_1.default.join(opts.targetDir, rule.from);
@@ -64,10 +125,41 @@ function applyMove(rule, opts) {
         return { rule, action: 'skipped', path: rule.to };
     }
     if (node_fs_1.default.existsSync(dest)) {
+        if (onConflict === 'fail') {
+            const found = findMergeConflicts(src, dest, rule.from, rule.to);
+            // 覆盖策略下同路径不同内容由搬迁源覆盖；类型不一致没有确定的合并结果，仍是冲突
+            const overwrite = opts.conflictPolicy === 'overwrite';
+            const conflicts = overwrite ? found.filter((c) => c.reason === TYPE_MISMATCH) : found;
+            const overwritten = overwrite
+                ? found
+                    .filter((c) => c.reason !== TYPE_MISMATCH)
+                    .map((c) => ({ ...c, reason: 'existing file replaced by the moved file' }))
+                : [];
+            if (conflicts.length > 0) {
+                (0, logger_1.log)(logPrefix, `  ✗ ${rule.from} → ${rule.to} (${conflicts.length.toString()} conflict(s))`);
+                return { rule, action: 'conflict', path: rule.to, detail: rule.from, conflicts };
+            }
+            if (opts.dryRun === true)
+                return planned(rule, rule.to);
+            mergeInto(src, dest, overwritten.length > 0);
+            node_fs_1.default.rmSync(src, { recursive: true, force: true });
+            (0, logger_1.log)(logPrefix, overwritten.length > 0
+                ? `  ✓ ${rule.from} → ${rule.to} (merged, ${overwritten.length.toString()} overwritten)`
+                : `  ✓ ${rule.from} → ${rule.to} (merged, no conflicts)`);
+            return {
+                rule,
+                action: 'moved',
+                path: rule.to,
+                detail: rule.from,
+                ...(overwritten.length > 0 ? { overwritten } : {}),
+            };
+        }
         if (onConflict === 'skip') {
             (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (already exists, skip per onConflict=skip)`);
             return { rule, action: 'skipped', path: rule.to };
         }
+        if (opts.dryRun === true)
+            return planned(rule, rule.to);
         if (onConflict === 'overwrite') {
             node_fs_1.default.rmSync(dest, { recursive: true, force: true });
             moveAtomic(src, dest);
@@ -81,6 +173,8 @@ function applyMove(rule, opts) {
         return { rule, action: 'moved', path: rule.to, detail: rule.from };
     }
     // 目标不存在 —— 直接 rename
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
     const destDir = node_path_1.default.dirname(dest);
     if (destDir !== '.' && !node_fs_1.default.existsSync(destDir)) {
         node_fs_1.default.mkdirSync(destDir, { recursive: true });
@@ -123,6 +217,591 @@ function mergeOverlay(src, dest) {
         mergeOverlay(node_path_1.default.join(src, entry), node_path_1.default.join(dest, entry));
     }
 }
+function posixJoin(a, b) {
+    return a === '' || a === '.' ? b : `${a}/${b}`;
+}
+/**
+ * 比对 src 合并进 dest 时的冲突：同路径不同内容、文件/目录类型不一致。
+ * 同内容文件不算冲突（幂等合并）。路径以项目根相对路径报告。
+ */
+function findMergeConflicts(src, dest, relFrom, relTo) {
+    const conflicts = [];
+    const srcStat = node_fs_1.default.statSync(src);
+    if (!node_fs_1.default.existsSync(dest))
+        return conflicts;
+    const destStat = node_fs_1.default.statSync(dest);
+    if (srcStat.isFile() || destStat.isFile()) {
+        if (!srcStat.isFile() || !destStat.isFile()) {
+            conflicts.push({ path: relTo, with: relFrom, reason: TYPE_MISMATCH });
+        }
+        else if (!node_fs_1.default.readFileSync(src).equals(node_fs_1.default.readFileSync(dest))) {
+            conflicts.push({ path: relTo, with: relFrom, reason: 'same path with different content' });
+        }
+        return conflicts;
+    }
+    for (const entry of node_fs_1.default.readdirSync(src).sort()) {
+        conflicts.push(...findMergeConflicts(node_path_1.default.join(src, entry), node_path_1.default.join(dest, entry), posixJoin(relFrom, entry), posixJoin(relTo, entry)));
+    }
+    return conflicts;
+}
+/**
+ * 把 src 的文件逐个合并进 dest。overwrite=false 时 dest 已有的文件（调用方已确认同内容）保持不动；
+ * overwrite=true 时 src 覆盖 dest 同路径文件（调用方已排除文件 / 目录类型不一致）。
+ */
+function mergeInto(src, dest, overwrite) {
+    const stat = node_fs_1.default.statSync(src);
+    if (stat.isFile()) {
+        if (!overwrite && node_fs_1.default.existsSync(dest))
+            return;
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(dest), { recursive: true });
+        node_fs_1.default.copyFileSync(src, dest);
+        node_fs_1.default.chmodSync(dest, stat.mode & 0o777);
+        return;
+    }
+    node_fs_1.default.mkdirSync(dest, { recursive: true });
+    for (const entry of node_fs_1.default.readdirSync(src)) {
+        mergeInto(node_path_1.default.join(src, entry), node_path_1.default.join(dest, entry), overwrite);
+    }
+}
+function listFilesRecursive(root, rel = '') {
+    const out = [];
+    for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(root, rel)).sort()) {
+        const childRel = rel === '' ? entry : `${rel}/${entry}`;
+        if (node_fs_1.default.statSync(node_path_1.default.join(root, childRel)).isDirectory()) {
+            out.push(...listFilesRecursive(root, childRel));
+        }
+        else {
+            out.push(childRel);
+        }
+    }
+    return out;
+}
+function readCapabilities(root, dirRel, conflicts) {
+    const caps = [];
+    const others = [];
+    const dirAbs = node_path_1.default.join(root, dirRel);
+    if (!node_fs_1.default.existsSync(dirAbs))
+        return { caps, others };
+    for (const rel of listFilesRecursive(dirAbs)) {
+        const relPath = `${dirRel}/${rel}`;
+        if (!rel.endsWith('.json')) {
+            others.push(rel);
+            continue;
+        }
+        const content = node_fs_1.default.readFileSync(node_path_1.default.join(dirAbs, rel));
+        let id = node_path_1.default.basename(rel, '.json');
+        try {
+            const parsed = JSON.parse(content.toString('utf-8'));
+            if (typeof parsed.id === 'string' && parsed.id !== '')
+                id = parsed.id;
+        }
+        catch {
+            conflicts.push({ path: relPath, reason: 'invalid capability JSON' });
+            continue;
+        }
+        caps.push({ path: relPath, rel, id, content });
+    }
+    return { caps, others };
+}
+function applyMoveCapabilities(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const srcAbs = node_path_1.default.join(opts.targetDir, rule.from);
+    if (!node_fs_1.default.existsSync(srcAbs)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.from} (source not found, skip)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const conflicts = [];
+    const src = readCapabilities(opts.targetDir, rule.from, conflicts);
+    const dest = readCapabilities(opts.targetDir, rule.to, conflicts);
+    // 同侧重复 ID
+    for (const side of [src.caps, dest.caps]) {
+        const seen = new Map();
+        for (const cap of side) {
+            const prev = seen.get(cap.id);
+            if (prev !== undefined) {
+                conflicts.push({
+                    path: cap.path,
+                    with: prev.path,
+                    id: cap.id,
+                    reason: 'duplicate capability id',
+                });
+            }
+            else {
+                seen.set(cap.id, cap);
+            }
+        }
+    }
+    // 跨侧同 ID：同文件同内容是幂等重跑，其他一律冲突
+    const destById = new Map(dest.caps.map((c) => [c.id, c]));
+    const destByRel = new Map(dest.caps.map((c) => [c.rel, c]));
+    for (const cap of src.caps) {
+        const sameId = destById.get(cap.id);
+        if (sameId !== undefined && !(sameId.rel === cap.rel && sameId.content.equals(cap.content))) {
+            conflicts.push({
+                path: sameId.path,
+                with: cap.path,
+                id: cap.id,
+                reason: 'capability id exists in both locations with different definition',
+            });
+            continue;
+        }
+        const sameRel = destByRel.get(cap.rel);
+        if (sameRel !== undefined && sameRel.id !== cap.id) {
+            conflicts.push({
+                path: sameRel.path,
+                with: cap.path,
+                reason: 'same file name with different capability id',
+            });
+        }
+    }
+    // 非 JSON 文件按同路径不同内容判定
+    for (const rel of src.others) {
+        const destFile = node_path_1.default.join(opts.targetDir, rule.to, rel);
+        if (!node_fs_1.default.existsSync(destFile))
+            continue;
+        if (!node_fs_1.default.readFileSync(node_path_1.default.join(srcAbs, rel)).equals(node_fs_1.default.readFileSync(destFile))) {
+            conflicts.push({
+                path: `${rule.to}/${rel}`,
+                with: `${rule.from}/${rel}`,
+                reason: 'same path with different content',
+            });
+        }
+    }
+    if (conflicts.length > 0 && opts.conflictPolicy === 'overwrite') {
+        return moveCapabilitiesOverwriting(rule, opts, conflicts, src.caps.length);
+    }
+    if (conflicts.length > 0) {
+        (0, logger_1.log)(logPrefix, `  ✗ ${rule.from} → ${rule.to} (${conflicts.length.toString()} conflict(s))`);
+        return { rule, action: 'conflict', path: rule.to, detail: rule.from, conflicts };
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
+    mergeInto(srcAbs, node_path_1.default.join(opts.targetDir, rule.to), false);
+    node_fs_1.default.rmSync(srcAbs, { recursive: true, force: true });
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.from} → ${rule.to} (${src.caps.length.toString()} capability file(s))`);
+    return {
+        rule,
+        action: 'moved',
+        path: rule.to,
+        detail: `${rule.from}; ${src.caps.length.toString()} capability file(s)`,
+    };
+}
+/**
+ * 覆盖策略下的插件搬迁：逐文件搬入，同路径由源覆盖（overwritten）。不同文件的同 ID、非法 JSON
+ * 没有可替换的模板内容、删任一侧都会丢用户插件，原样搬入并记 kept；类型不一致仍是冲突。
+ */
+function moveCapabilitiesOverwriting(rule, opts, idConflicts, capCount) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const srcAbs = node_path_1.default.join(opts.targetDir, rule.from);
+    const destAbs = node_path_1.default.join(opts.targetDir, rule.to);
+    const found = findMergeConflicts(srcAbs, destAbs, rule.from, rule.to);
+    const blocking = found.filter((c) => c.reason === TYPE_MISMATCH);
+    if (blocking.length > 0) {
+        (0, logger_1.log)(logPrefix, `  ✗ ${rule.from} → ${rule.to} (${blocking.length.toString()} conflict(s))`);
+        return { rule, action: 'conflict', path: rule.to, detail: rule.from, conflicts: blocking };
+    }
+    const overwritten = found.map((c) => ({
+        ...c,
+        reason: 'existing file replaced by the moved file',
+    }));
+    const replaced = new Set(overwritten.map((c) => c.path));
+    const kept = idConflicts.filter((c) => !replaced.has(c.path));
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
+    mergeInto(srcAbs, destAbs, true);
+    node_fs_1.default.rmSync(srcAbs, { recursive: true, force: true });
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.from} → ${rule.to} (${capCount.toString()} capability file(s); ${overwritten.length.toString()} overwritten, ${kept.length.toString()} kept)`);
+    return {
+        rule,
+        action: 'moved',
+        path: rule.to,
+        detail: `${rule.from}; ${capCount.toString()} capability file(s)`,
+        ...(overwritten.length > 0 ? { overwritten } : {}),
+        ...(kept.length > 0 ? { kept } : {}),
+    };
+}
+function readJsonFile(abs) {
+    const text = node_fs_1.default.readFileSync(abs, 'utf-8');
+    try {
+        const json = JSON.parse(text);
+        if (json === null || typeof json !== 'object' || Array.isArray(json))
+            return undefined;
+        return { text, json: json };
+    }
+    catch {
+        return undefined;
+    }
+}
+function applyEnsureScripts(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const rel = rule.to ?? 'package.json';
+    const abs = node_path_1.default.join(opts.targetDir, rel);
+    if (!node_fs_1.default.existsSync(abs)) {
+        return {
+            rule,
+            action: 'conflict',
+            path: rel,
+            conflicts: [{ path: rel, reason: 'package.json not found' }],
+        };
+    }
+    const parsed = readJsonFile(abs);
+    if (parsed === undefined) {
+        return {
+            rule,
+            action: 'conflict',
+            path: rel,
+            conflicts: [{ path: rel, reason: 'package.json is not a valid JSON object' }],
+        };
+    }
+    const current = (parsed.json.scripts ?? {});
+    const outcome = (0, migrate_adapters_1.ensureScripts)(current, rule.scripts);
+    const policy = opts.conflictPolicy ?? 'stop';
+    if (outcome.conflicts.length > 0 && policy === 'stop') {
+        const conflicts = outcome.conflicts.map((c) => ({
+            path: `${rel}#scripts.${c.name}`,
+            reason: `custom script ${JSON.stringify(c.current)} differs from required ${JSON.stringify(c.expected)}; keep business steps in another script name or align it manually`,
+        }));
+        (0, logger_1.log)(logPrefix, `  ✗ ${rel} scripts (${conflicts.length.toString()} conflict(s))`);
+        return { rule, action: 'conflict', path: rel, conflicts };
+    }
+    const overwritten = [];
+    const kept = [];
+    for (const c of outcome.conflicts) {
+        const spec = rule.scripts.find((s) => s.name === c.name);
+        const at = `${rel}#scripts.${c.name}`;
+        if (policy === 'overwrite' && spec?.keepCustom !== true) {
+            outcome.scripts[c.name] = c.expected;
+            outcome.changed.push(c.name);
+            overwritten.push({
+                path: at,
+                reason: `custom script ${JSON.stringify(c.current)} replaced with ${JSON.stringify(c.expected)}`,
+            });
+        }
+        else {
+            kept.push({
+                path: at,
+                reason: `custom script ${JSON.stringify(c.current)} kept; platform expects ${JSON.stringify(c.expected)}`,
+            });
+        }
+    }
+    const extra = {
+        ...(overwritten.length > 0 ? { overwritten } : {}),
+        ...(kept.length > 0 ? { kept } : {}),
+    };
+    const keptNote = kept.length > 0 ? `; kept custom: ${kept.length.toString()}` : '';
+    if (outcome.changed.length === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rel} scripts (already aligned${keptNote})`);
+        return { rule, action: 'noop', path: rel, ...extra };
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rel);
+    parsed.json.scripts = outcome.scripts;
+    const trailing = parsed.text.endsWith('\n') ? '\n' : '';
+    node_fs_1.default.writeFileSync(abs, JSON.stringify(parsed.json, null, 2) + trailing);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rel} scripts (${outcome.changed.join(', ')}${keptNote})`);
+    return { rule, action: 'patched', path: rel, detail: outcome.changed.join(','), ...extra };
+}
+function applyAdaptTsconfig(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const tplAbs = node_path_1.default.join(opts.sourceRoot, rule.from);
+    const userAbs = node_path_1.default.join(opts.targetDir, rule.to);
+    if (!node_fs_1.default.existsSync(tplAbs)) {
+        (0, logger_1.log)(logPrefix, `  ⚠ template ${rule.from} not found, skip`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const userExists = node_fs_1.default.existsSync(userAbs);
+    if (!userExists && rule.role === 'app') {
+        // app 侧缺失：直接采用模板（无用户内容可保留）
+        if (opts.dryRun === true)
+            return planned(rule, rule.to);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(userAbs), { recursive: true });
+        node_fs_1.default.copyFileSync(tplAbs, userAbs);
+        (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (created from template)`);
+        return { rule, action: 'created', path: rule.to };
+    }
+    const result = (0, migrate_adapters_1.adaptTsconfig)({
+        role: rule.role,
+        userText: userExists ? node_fs_1.default.readFileSync(userAbs, 'utf-8') : undefined,
+        templateText: node_fs_1.default.readFileSync(tplAbs, 'utf-8'),
+        legacyExtends: rule.legacyExtends,
+    });
+    if (!result.ok && opts.conflictPolicy === 'overwrite') {
+        if (opts.dryRun === true)
+            return planned(rule, rule.to);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(userAbs), { recursive: true });
+        node_fs_1.default.copyFileSync(tplAbs, userAbs);
+        (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (${result.conflict}; replaced with template)`);
+        return {
+            rule,
+            action: 'synced',
+            path: rule.to,
+            detail: 'replaced with template',
+            overwritten: [{ path: rule.to, reason: `${result.conflict}; replaced with template` }],
+        };
+    }
+    if (!result.ok) {
+        (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (${result.conflict})`);
+        return {
+            rule,
+            action: 'conflict',
+            path: rule.to,
+            conflicts: [{ path: rule.to, reason: result.conflict }],
+        };
+    }
+    if (!result.changed) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (already adapted)`);
+        return { rule, action: 'noop', path: rule.to };
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(userAbs), { recursive: true });
+    node_fs_1.default.writeFileSync(userAbs, result.text);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (${result.detail ?? 'adapted'})`);
+    return { rule, action: userExists ? 'patched' : 'created', path: rule.to, detail: result.detail };
+}
+function applyAdaptHtmlEntry(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const fromAbs = node_path_1.default.join(opts.targetDir, rule.from);
+    const toAbs = node_path_1.default.join(opts.targetDir, rule.to);
+    const tplAbs = node_path_1.default.join(opts.sourceRoot, rule.template);
+    if (!node_fs_1.default.existsSync(tplAbs)) {
+        (0, logger_1.log)(logPrefix, `  ⚠ template ${rule.template} not found, skip`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    if (!node_fs_1.default.existsSync(fromAbs)) {
+        if (node_fs_1.default.existsSync(toAbs)) {
+            (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (already present)`);
+            return { rule, action: 'noop', path: rule.to };
+        }
+        if (opts.dryRun === true)
+            return planned(rule, rule.to);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(toAbs), { recursive: true });
+        node_fs_1.default.copyFileSync(tplAbs, toAbs);
+        (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (created from template)`);
+        return { rule, action: 'created', path: rule.to };
+    }
+    const templateHtml = node_fs_1.default.readFileSync(tplAbs, 'utf-8');
+    const result = (0, migrate_adapters_1.adaptHtmlEntry)({
+        userHtml: node_fs_1.default.readFileSync(fromAbs, 'utf-8'),
+        templateHtml,
+        legacyEntry: rule.legacyEntry,
+    });
+    const overwrite = opts.conflictPolicy === 'overwrite';
+    const overwritten = [];
+    if (!result.ok) {
+        if (!overwrite) {
+            (0, logger_1.log)(logPrefix, `  ✗ ${rule.from} (${result.conflict})`);
+            return {
+                rule,
+                action: 'conflict',
+                path: rule.from,
+                conflicts: [{ path: rule.from, reason: result.conflict }],
+            };
+        }
+        overwritten.push({
+            path: rule.from,
+            reason: `${result.conflict}; replaced with template ${rule.to}`,
+        });
+    }
+    const text = result.ok ? result.text : templateHtml;
+    if (node_fs_1.default.existsSync(toAbs) && node_fs_1.default.readFileSync(toAbs, 'utf-8') !== text) {
+        const reason = 'both legacy and new HTML entries exist with different content';
+        if (!overwrite) {
+            return {
+                rule,
+                action: 'conflict',
+                path: rule.to,
+                conflicts: [{ path: rule.to, with: rule.from, reason }],
+            };
+        }
+        overwritten.push({ path: rule.to, with: rule.from, reason: `${reason}; replaced` });
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(toAbs), { recursive: true });
+    node_fs_1.default.writeFileSync(toAbs, text);
+    node_fs_1.default.unlinkSync(fromAbs);
+    const detail = result.ok ? result.detail : 'replaced with template';
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.from} → ${rule.to} (${detail ?? 'adapted'})`);
+    return {
+        rule,
+        action: 'patched',
+        path: rule.to,
+        detail,
+        ...(overwritten.length > 0 ? { overwritten } : {}),
+    };
+}
+function applyAdaptNestAppModule(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const rel = rule.to ?? 'server/app.module.ts';
+    const mainRel = rule.checkMain ?? 'server/main.ts';
+    const conflicts = [];
+    // 覆盖策略下冲突文件换成模板同路径文件；模板缺该文件时无可替换内容，仍是冲突
+    const replaceable = (fileRel) => opts.conflictPolicy === 'overwrite' && node_fs_1.default.existsSync(node_path_1.default.join(opts.sourceRoot, fileRel));
+    const replaced = [];
+    const mainAbs = node_path_1.default.join(opts.targetDir, mainRel);
+    if (node_fs_1.default.existsSync(mainAbs) &&
+        !node_fs_1.default.readFileSync(mainAbs, 'utf-8').includes('@lark-apaas/fullstack-nestjs-core')) {
+        const reason = 'server bootstrap does not use @lark-apaas/fullstack-nestjs-core (configureApp)';
+        if (replaceable(mainRel)) {
+            replaced.push({ path: mainRel, reason: `${reason}; replaced with template` });
+        }
+        else {
+            conflicts.push({ path: mainRel, reason });
+        }
+    }
+    const abs = node_path_1.default.join(opts.targetDir, rel);
+    let moduleText;
+    let detail;
+    if (node_fs_1.default.existsSync(abs)) {
+        const includeView = node_fs_1.default.existsSync(node_path_1.default.join(node_path_1.default.dirname(abs), 'modules', 'view', 'view.module.ts'));
+        const result = (0, migrate_adapters_1.adaptNestAppModule)(node_fs_1.default.readFileSync(abs, 'utf-8'), { includeView });
+        if (result.ok) {
+            if (result.changed)
+                moduleText = result.text;
+            detail = result.detail;
+        }
+        else if (replaceable(rel)) {
+            replaced.push({ path: rel, reason: `${result.conflict}; replaced with template` });
+        }
+        else {
+            conflicts.push({ path: rel, reason: result.conflict });
+        }
+    }
+    if (conflicts.length > 0) {
+        (0, logger_1.log)(logPrefix, `  ✗ ${rel} (${conflicts.length.toString()} conflict(s))`);
+        return { rule, action: 'conflict', path: rel, conflicts };
+    }
+    if (replaced.length === 0 && moduleText === undefined) {
+        if (!node_fs_1.default.existsSync(abs)) {
+            (0, logger_1.log)(logPrefix, `  ○ ${rel} (not found, skip)`);
+            return { rule, action: 'skipped', path: rel };
+        }
+        (0, logger_1.log)(logPrefix, `  ○ ${rel} (platform modules already registered)`);
+        return { rule, action: 'noop', path: rel };
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rel);
+    for (const c of replaced) {
+        node_fs_1.default.copyFileSync(node_path_1.default.join(opts.sourceRoot, c.path), node_path_1.default.join(opts.targetDir, c.path));
+    }
+    if (moduleText !== undefined)
+        node_fs_1.default.writeFileSync(abs, moduleText);
+    const summary = [
+        ...(detail !== undefined && moduleText !== undefined ? [detail] : []),
+        ...replaced.map((c) => `${c.path} replaced with template`),
+    ].join('; ');
+    (0, logger_1.log)(logPrefix, `  ✓ ${rel} (${summary})`);
+    return {
+        rule,
+        action: 'patched',
+        path: rel,
+        detail: summary,
+        ...(replaced.length > 0 ? { overwritten: replaced } : {}),
+    };
+}
+function applyRemoveKnownDefault(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const abs = node_path_1.default.join(opts.targetDir, rule.to);
+    if (!node_fs_1.default.existsSync(abs)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const customized = !(0, migrate_adapters_1.matchesKnownDefault)(node_fs_1.default.readFileSync(abs, 'utf-8'), rule.knownDefaults);
+    if (customized && opts.conflictPolicy !== 'overwrite') {
+        (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (customized)`);
+        return {
+            rule,
+            action: 'conflict',
+            path: rule.to,
+            conflicts: [{ path: rule.to, reason: rule.reason }],
+        };
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
+    node_fs_1.default.unlinkSync(abs);
+    if (customized) {
+        (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (customized, removed)`);
+        return {
+            rule,
+            action: 'deleted',
+            path: rule.to,
+            overwritten: [{ path: rule.to, reason: 'customized legacy config removed' }],
+        };
+    }
+    (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (platform default removed)`);
+    return { rule, action: 'deleted', path: rule.to };
+}
+function applyCarryEslintIgnores(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const legacyAbs = node_path_1.default.join(opts.targetDir, rule.from);
+    if (!node_fs_1.default.existsSync(legacyAbs)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.from} (not found, no ignores to carry)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    // 预检时新配置可能还没由前序 file 规则补齐：按将要落地的模板版本判定
+    let targetAbs = node_path_1.default.join(opts.targetDir, rule.to);
+    if (!node_fs_1.default.existsSync(targetAbs) && opts.dryRun === true) {
+        targetAbs = node_path_1.default.join(opts.sourceRoot, rule.to);
+    }
+    if (!node_fs_1.default.existsSync(targetAbs)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip carrying ignores)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const result = (0, migrate_adapters_1.carryEslintIgnores)({
+        legacyText: node_fs_1.default.readFileSync(legacyAbs, 'utf-8'),
+        targetText: node_fs_1.default.readFileSync(targetAbs, 'utf-8'),
+    });
+    if (!result.ok) {
+        const found = { path: rule.to, reason: result.conflict, with: rule.from };
+        if (opts.conflictPolicy === 'overwrite') {
+            // 没有可替换的模板内容：新配置是用户自己的，保留原样
+            (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (${result.conflict}, kept)`);
+            return { rule, action: 'skipped', path: rule.to, kept: [found] };
+        }
+        (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (${result.conflict})`);
+        return { rule, action: 'conflict', path: rule.to, conflicts: [found] };
+    }
+    if (!result.changed) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (${result.detail ?? 'nothing to carry'})`);
+        return { rule, action: 'noop', path: rule.to, detail: result.detail };
+    }
+    if (opts.dryRun === true)
+        return planned(rule, rule.to);
+    node_fs_1.default.writeFileSync(targetAbs, result.text);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (${result.detail ?? 'ignores carried'})`);
+    return { rule, action: 'patched', path: rule.to, detail: result.detail };
+}
+function applyRelaxEslintRules(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const abs = node_path_1.default.join(opts.targetDir, rule.to);
+    if (!node_fs_1.default.existsSync(abs)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip relaxing rules)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const result = (0, migrate_adapters_1.relaxEslintRules)({
+        text: node_fs_1.default.readFileSync(abs, 'utf-8'),
+        files: rule.files,
+        rules: rule.rules,
+    });
+    if (!result.ok) {
+        // 用户自己的配置形态：不改，记 kept；规则仍按 preset 生效，交给提交 hooks 判定
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (${result.conflict}, kept)`);
+        return {
+            rule,
+            action: 'skipped',
+            path: rule.to,
+            kept: [{ path: rule.to, reason: result.conflict }],
+        };
+    }
+    if (!result.changed) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (${result.detail ?? 'unchanged'})`);
+        return { rule, action: 'noop', path: rule.to, detail: result.detail };
+    }
+    node_fs_1.default.writeFileSync(abs, result.text);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (${result.detail ?? 'rules relaxed'})`);
+    return { rule, action: 'patched', path: rule.to, detail: result.detail };
+}
 function applySetStack(rule, opts) {
     const logPrefix = opts.logPrefix ?? 'migrate';
     (0, spark_meta_1.writeSparkMeta)(opts.targetDir, { stack: rule.stack });
@@ -179,23 +858,77 @@ function applyCodemodViteConfigFullstack(rule, opts) {
     const rel = rule.to ?? 'vite.config.ts';
     const dest = node_path_1.default.join(opts.targetDir, rel);
     if (!node_fs_1.default.existsSync(dest)) {
+        const others = [
+            'vite.config.js',
+            'vite.config.mjs',
+            'vite.config.mts',
+            'vite.config.cjs',
+        ].filter((f) => node_fs_1.default.existsSync(node_path_1.default.join(opts.targetDir, node_path_1.default.dirname(rel), f)));
+        if (others.length > 0) {
+            const found = [{ path: others[0], reason: `unsupported vite config file; expected ${rel}` }];
+            if (opts.conflictPolicy === 'overwrite') {
+                (0, logger_1.log)(logPrefix, `  ○ ${others[0]} (unsupported vite config file, kept)`);
+                return { rule, action: 'skipped', path: others[0], kept: found };
+            }
+            return { rule, action: 'conflict', path: others[0], conflicts: found };
+        }
+        const tplAbs = rule.template !== undefined ? node_path_1.default.join(opts.sourceRoot, rule.template) : '';
+        if (tplAbs !== '' && node_fs_1.default.existsSync(tplAbs)) {
+            if (opts.dryRun === true)
+                return planned(rule, rel);
+            node_fs_1.default.copyFileSync(tplAbs, dest);
+            (0, logger_1.log)(logPrefix, `  ✓ ${rel} (created from template)`);
+            return { rule, action: 'created', path: rel };
+        }
         (0, logger_1.log)(logPrefix, `  ○ ${rel} (not found, skip)`);
         return { rule, action: 'skipped', path: rel };
     }
-    const before = node_fs_1.default.readFileSync(dest, 'utf-8');
+    const original = node_fs_1.default.readFileSync(dest, 'utf-8');
+    const { text: before, replaced: presetReplaced } = replaceLegacyPreset(original, rule);
+    const kept = [];
+    if (rule.requirePreset !== undefined && !before.includes(rule.requirePreset)) {
+        const found = {
+            path: rel,
+            reason: `vite config does not use ${rule.requirePreset}; fullstack dev proxy cannot be enabled automatically`,
+        };
+        if (opts.conflictPolicy !== 'overwrite') {
+            (0, logger_1.log)(logPrefix, `  ✗ ${rel} (does not use ${rule.requirePreset})`);
+            return { rule, action: 'conflict', path: rel, conflicts: [found] };
+        }
+        kept.push(found);
+    }
+    const extra = kept.length > 0 ? { kept } : {};
     const { text, aliasRewriteCount } = rewriteViteConfigForFullstack(before);
-    if (aliasRewriteCount === 0) {
+    if (aliasRewriteCount === 0 && presetReplaced === undefined) {
         (0, logger_1.log)(logPrefix, `  ○ ${rel} (no src alias path to rewrite)`);
-        return { rule, action: 'noop', path: rel };
+        return { rule, action: 'noop', path: rel, ...extra };
     }
+    if (opts.dryRun === true)
+        return planned(rule, rel);
     node_fs_1.default.writeFileSync(dest, text);
-    (0, logger_1.log)(logPrefix, `  ✓ ${rel} (rewrote ${aliasRewriteCount.toString()} alias path(s) src → client/src)`);
-    return {
-        rule,
-        action: 'patched',
-        path: rel,
-        detail: `${aliasRewriteCount.toString()} alias path(s)`,
-    };
+    const details = [`${aliasRewriteCount.toString()} alias path(s)`];
+    if (presetReplaced !== undefined)
+        details.push(`preset ${presetReplaced} → ${rule.requirePreset ?? ''}`);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rel} (${details.join('; ')})`);
+    return { rule, action: 'patched', path: rel, detail: details.join('; '), ...extra };
+}
+/**
+ * 配置从 legacyPresets 之一 import（且没用 requirePreset）时，把模块名改写为 requirePreset。
+ * 只改 import / require 的模块名字符串，引号原样保留。
+ */
+function replaceLegacyPreset(source, rule) {
+    const target = rule.requirePreset;
+    if (target === undefined || source.includes(target))
+        return { text: source };
+    for (const legacy of rule.legacyPresets ?? []) {
+        const escaped = legacy.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+        const re = new RegExp(`((?:\\bfrom\\s*|\\b(?:require|import)\\s*\\(\\s*)(['"]))${escaped}\\2`, 'g');
+        if (!re.test(source))
+            continue;
+        re.lastIndex = 0;
+        return { text: source.replace(re, `$1${target}$2`), replaced: legacy };
+    }
+    return { text: source };
 }
 /**
  * 把 vite.config.ts 里 alias 字符串里 `src` 起头的路径重写到 `client/src`。
@@ -264,6 +997,8 @@ function applyAddDepsFromTemplate(rule, opts) {
     const userText = node_fs_1.default.readFileSync(userPath, 'utf-8');
     const userJson = JSON.parse(userText);
     const tplJson = JSON.parse(node_fs_1.default.readFileSync(tplPath, 'utf-8'));
+    const exact = new Set(rule.exactFromLock ?? []);
+    const locked = exact.size > 0 ? readLockedVersions(node_path_1.default.join(node_path_1.default.dirname(tplPath), 'package-lock.json')) : {};
     const added = [];
     const missingInTpl = [];
     for (const grp of ['dependencies', 'devDependencies']) {
@@ -274,18 +1009,25 @@ function applyAddDepsFromTemplate(rule, opts) {
         for (const dep of whitelist) {
             // 在 template 里找版本号：优先 tpl 同 grp，其次另一 grp（template 可能把 dep 写在
             // dependencies/devDependencies 任一处，跟 user 当前 grp 不一定一致）
-            const tplVersion = tplJson[grp]?.[dep] ??
+            const tplRange = tplJson[grp]?.[dep] ??
                 (grp === 'dependencies' ? tplJson.devDependencies?.[dep] : tplJson.dependencies?.[dep]);
+            const tplVersion = tplRange !== undefined && exact.has(dep) ? (locked[dep] ?? tplRange) : tplRange;
             if (tplVersion === undefined) {
                 missingInTpl.push(dep);
                 continue;
             }
+            const existing = userJson.dependencies?.[dep] ?? userJson.devDependencies?.[dep];
+            if (existing === tplVersion)
+                continue;
+            // repair 模式只补缺失依赖：用户在已转换工程上主动升级过的版本不回退
+            if (opts.mode === 'repair' && existing !== undefined)
+                continue;
             userJson[grp][dep] = tplVersion;
             added.push(`${grp}.${dep}`);
         }
     }
-    if (added.length === 0 && missingInTpl.length === 0) {
-        (0, logger_1.log)(logPrefix, `  ○ ${rule.to ?? 'package.json'} (no deps to add)`);
+    if (added.length === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to ?? 'package.json'} (no deps to add${missingInTpl.length > 0 ? `; missing in template: ${missingInTpl.join(', ')}` : ''})`);
         return { rule, action: 'noop', path: rule.to ?? 'package.json' };
     }
     const trailing = userText.endsWith('\n') ? '\n' : '';
@@ -298,6 +1040,29 @@ function applyAddDepsFromTemplate(rule, opts) {
         detail: added.join(','),
     };
 }
+/**
+ * 读模板 lockfile（npm v2/v3 的 packages 结构）里顶层安装的包版本：`node_modules/<name>` →
+ * version。lockfile 缺失或不可解析时返回空表，调用方退回 package.json 的 range。
+ */
+function readLockedVersions(lockPath) {
+    if (!node_fs_1.default.existsSync(lockPath))
+        return {};
+    try {
+        const lock = JSON.parse(node_fs_1.default.readFileSync(lockPath, 'utf-8'));
+        const versions = {};
+        for (const [key, entry] of Object.entries(lock.packages ?? {})) {
+            const name = key.startsWith('node_modules/') ? key.slice('node_modules/'.length) : undefined;
+            if (name === undefined || name.includes('/node_modules/'))
+                continue;
+            if (typeof entry.version === 'string')
+                versions[name] = entry.version;
+        }
+        return versions;
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * 按 dot path 删除嵌套对象里的一个 leaf key。返回是否真的删了一项。
  * 不支持包含 `.` 的字段名（实际 dep 名 / scripts 名不会含 `.`，够用）。