@lark-apaas/miaoda-cli 0.1.46 → 0.1.47

package/dist/cli/handlers/app/migrate.js

@@ -4,239 +4,157 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleAppMigrate = handleAppMigrate;
-const node_child_process_1 = require("node:child_process");
-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 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 index_1 = require("../../../services/app/migrate/index");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const env_1 = require("../../../utils/env");
 const logger_1 = require("../../../utils/logger");
-const run_npm_1 = require("../../../utils/run-npm");
+const package_json_1 = __importDefault(require("../../../../package.json"));
 /**
- * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
+ * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>] [--purpose <p>] [--operation-ref <id>]
  *
- * 跨 stack 原地迁移：把 user app 从源 stack（默认 .spark/meta.json 当前 stack）转到目标 stack。
- * 同一个 git 仓库内进行，不动 git history，所有改动作为 working tree 变更体现，用户跑完后
- * 自行 `git status` / `git diff` 评估并 commit。
+ * 工程转换原语的 CLI 入口：参数校验 + 结构化输出，转换流程在 services/app/migrate。
  *
- * 跟 sync 的区别：sync 是同 stack 内的版本对齐，migrate 是跨 stack 切换（布局重排、依赖
- * 集合切换、配置文件全套替换）。两条命令的 rule 引擎共享（applyMigrateRules 内部对
- * SyncRule 委派给 applySyncRules）。
+ * 结果语义：
+ *   status=converted：原目录内文件适配、依赖安装、配置了的验证步骤全部完成。
+ *     conflictPolicy=overwrite 时被模板替换的用户内容列在 overwritten；保留未适配的位置是
+ *     code=MIGRATE_CONFLICT_KEPT 的 warning。
+ *     运行 readiness 不在 CLI 内判定（readiness.status=pending_caller_verification）——
+ *     沙箱里 restartSignalSent / devRestarted 只表示向本目录的 dev 进程发出了重启信号，不是健康结果。
+ *   status=conflict：存在当前冲突策略下无法处理的冲突（conflicts 给出具体路径 / ID），冲突文件不覆盖；
+ *     预检阶段发现时工程未写入（originalIntact=true），应用阶段发现时可能已有部分改动。
+ *   status=failed：某阶段失败（failure.stage / code），现场原样保留、不自动回滚；
+ *     originalIntact=true 仅表示失败发生在任何工程写入之前。
+ *   非 converted 退出码 1，唯一例外见 isLenientInstallFailure：manual 调用只是依赖没装上时退出码 0。
  *
- * 执行流：
- *   1. 校验 user app 已 init（.spark/meta.json 存在）+ 当前 stack 匹配 from
- *   2. 拿到 (from, to) 对应的 MigrateConfig 与模板源根目录
- *   3. 顺序执行 rules：move-* → delete-* → delete-json-keys → file/directory →
- *      merge-json → set-stack
- *   4. 清掉 node_modules（package-lock.json 已经在 rules 里 delete），跑 npm install
- *      物化新依赖集合 —— migrate 改了 dependencies / devDependencies 集合（删 lite +
- *      加 NestJS 全套），不重装就跑不起来。
- *      同一条 npm install 顺手把 config.followLatestPackages 钉 `@latest`，覆盖
- *      template caret range 拉不到 pre-release 的盲区（详见 MigrateConfig 注释）。
- *
- * 不做事：
- *   - 不自动 commit / stash —— 让用户自己用 git review 改动
- *   - 不动 .agent/skills/（那是 miaoda skills sync 的事，迁移后用户应该单独跑一次切到新 stack 的 skills）
+ * 同目标（磁盘已是目标布局）不再返回 MIGRATE_NOOP：走 repair 模式补齐适配 / 安装 / 构建，
+ * 支持"平台已新但恢复了旧代码"与"目标 meta 已写、安装未完成"的样本。
  */
 async function handleAppMigrate(opts) {
     await Promise.resolve();
-    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
-    if (meta.stack === undefined || meta.stack === '') {
-        throw new error_1.AppError('MIGRATE_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
-    }
-    const from = opts.from ?? meta.stack;
-    if (opts.from !== undefined && opts.from !== meta.stack) {
-        throw new error_1.AppError('MIGRATE_FROM_MISMATCH', `--from '${opts.from}' but current stack is '${meta.stack}'`, {
-            next_actions: ['省略 --from 让 cli 自动读 meta.json，或确认 user app 状态'],
-        });
-    }
-    if (from === opts.to) {
-        throw new error_1.AppError('MIGRATE_NOOP', `from and to are both '${from}', nothing to do`);
-    }
-    const config = (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)'}`],
-        });
-    }
-    // migrate 用 init 同款的 renderTemplate 拉目标 stack 的 npm template tarball 到 tmp，
-    // 再把 tmp 当作 sourceRoot 喂给 applyMigrateRules。这样 migrate config 里 file/directory
-    // rule 的 `from` 引用的是完整的 npm template 渲染产物，不需要在 upgrade/templates/ 重复
-    // 维护一份 server/ + client/ + 全套配置 —— 复杂度由 init 那条链路 amortize。
-    const tmpRoot = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-migrate-'));
-    const projectName = node_path_1.default.basename(targetDir);
-    let templateVersion;
-    let templateArchType;
-    let results;
-    try {
-        const tpl = (0, index_2.renderTemplate)({ stack: opts.to, targetDir: tmpRoot, projectName });
-        templateVersion = tpl.version;
-        templateArchType = tpl.archType;
-        // template package.json 的 user 私有字段（name / version / private 等）不参与 merge —— 否
-        // 则会被 deepMergeJson 当成 template 端"权威值"覆盖 user 项目原本的字段。这里在 tmp 端
-        // 直接 strip 这些字段，让 merge-json rule 只对 dependencies / devDependencies / scripts
-        // 等 schema-level 字段生效。
-        stripUserOwnedFields(node_path_1.default.join(tmpRoot, 'package.json'));
-        (0, logger_1.log)('migrate', `Rendered ${opts.to}@${tpl.version} to tmp, applying ${config.rules.length.toString()} rule(s)`);
-        results = (0, migrate_rule_1.applyMigrateRules)(config.rules, {
-            sourceRoot: tmpRoot,
-            targetDir,
-            logPrefix: 'migrate',
-        });
-    }
-    finally {
-        node_fs_1.default.rmSync(tmpRoot, { recursive: true, force: true });
-    }
-    // archType / version 字段同步：set-stack rule 只切 stack，archType 是从 npm template 包
-    // 的 miaodaTemplate.archType 拿到的动态值，rule 配置时不知道，由 handler 在拿到
-    // renderTemplate 结果后单独写。version 也一并写回方便 sync 后续诊断。
-    (0, spark_meta_1.writeSparkMeta)(targetDir, { archType: templateArchType, version: templateVersion });
-    // 清掉 user app 的 node_modules —— migrate 改了 dependencies 集合（删 lite + 加 NestJS
-    // 全套）+ rule 已经把 package-lock.json 删了。如果 node_modules 留着，npm install 时旧
-    // 包还在 node_modules 顶层 hoist 树里，可能跟新 package.json spec 撞 peer 冲突
-    // （比如旧 coding-preset-vite-react@1.0.8 peer vite@^8 跟新 vite@^7 撞）。
-    // 软失败：node_modules 不存在不报错。
-    const nodeModulesPath = node_path_1.default.join(targetDir, 'node_modules');
-    if (node_fs_1.default.existsSync(nodeModulesPath)) {
-        (0, logger_1.log)('migrate', '清理 node_modules（dependencies 集合已变）...');
-        node_fs_1.default.rmSync(nodeModulesPath, { recursive: true, force: true });
-    }
-    // 跑 npm install 物化新依赖集合 + 把 followLatestPackages 钉 latest
-    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
-    // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
-    // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
-    const followLatest = config.followLatestPackages ?? [];
-    const installArgs = [
-        'install',
-        '--no-audit',
-        '--no-fund',
-        '--ignore-scripts',
-        '--registry',
-        (0, index_2.resolveNpmInstallRegistry)(),
-        ...followLatest.map((pkg) => `${pkg}@latest`),
-    ];
-    (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
-    let installError;
-    try {
-        (0, run_npm_1.execNpmSync)(installArgs, {
-            cwd: targetDir,
-            stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+    const purpose = opts.purpose ?? 'manual';
+    if (!index_1.MIGRATION_PURPOSES.includes(purpose)) {
+        throw new error_1.AppError('ARGS_INVALID', `不支持的 --purpose: ${purpose}`, {
+            next_actions: [`可用值：${index_1.MIGRATION_PURPOSES.join(', ')}`],
         });
     }
-    catch (err) {
-        installError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
-    }
-    // 重启 dev process 前清 vite cache —— migrate 改了 package.json + lockfile,
-    // 老 vite 进程的 .vite/deps cache 的 lockfileHash 跟新 lockfile 不一致。
-    // 不清的话 supervisor 拉起的新 vite cold start 会立即 "Re-optimizing because
-    // lockfile has changed", re-optimize 期间 ModuleGraph transform cache 跟
-    // deps middleware metadata 短暂不同步, 浏览器请求老 hash 触发
-    // ERR_OUTDATED_OPTIMIZED_DEP → 504 死锁(详见 fullstack-plugin#1143 的 504
-    // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
-    // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
-    //
-    //   - 只在沙箱内做(isSandboxEnv;本地一般不会撞这条链路)
-    //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
-    //   - 软失败:.vite 不存在 / 删失败都不阻断
-    if (installError === undefined && (0, env_1.isSandboxEnv)()) {
-        const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
-        if (node_fs_1.default.existsSync(viteCacheDir)) {
-            (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');
-            try {
-                node_fs_1.default.rmSync(viteCacheDir, { recursive: true, force: true });
-            }
-            catch (err) {
-                (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
+    const sandbox = (0, env_1.isSandboxEnv)();
+    const outcome = (0, index_1.runMigration)({
+        targetDir: node_path_1.default.resolve(opts.dir ?? process.cwd()),
+        to: opts.to,
+        from: opts.from,
+        appId: opts.appId,
+        purpose: purpose,
+        operationRef: opts.operationRef,
+        sandbox,
+        cliVersion: package_json_1.default.version,
+        quietStdout: (0, output_1.isJsonMode)(),
+    });
+    const data = toOutput(outcome, sandbox);
+    (0, output_1.emit)({ data });
+    if (isLenientInstallFailure(outcome)) {
+        (0, logger_1.log)('migrate', '⚠ npm install failed (continuing): 文件已转换，依赖需调用方补装');
+        return;
     }
-    // 沙箱环境下重启 dev process —— scripts/dev.js 被 fullstack 版本覆盖了,但当前正在
-    // 跑的 node 进程仍按老逻辑工作(只起 vite,没起 nest),整体没切到 fullstack 模式。
-    // 通过 pkill 杀掉 dev.js 主进程,依赖沙箱平台 supervisor 自动重新 exec dev.sh → dev.js,
-    // 新进程用新 deps + 新 scripts,正常进入 fullstack 模式。
-    //   - 只在沙箱内做(isSandboxEnv;本地环境用户进程混杂,主动 pkill 风险大)
-    //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
-    //     留着旧进程让用户先处理 installError
-    //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
-    //   - pkill 是 POSIX-only,但整段被 isSandboxEnv() 包着(沙箱恒为 Linux),
-    //     Windows 本地永远走不到这里,故不需要跨平台封装
-    let devRestarted = false;
-    if (installError === undefined && (0, env_1.isSandboxEnv)()) {
-        (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');
-        try {
-            (0, node_child_process_1.execFileSync)('pkill', ['-f', 'node.*scripts/dev\\.js'], { stdio: 'ignore' });
-            devRestarted = true;
-        }
-        catch {
-            // pkill 无匹配进程时退出 1,正常情况(可能 dev 没在跑)
-        }
+    if (outcome.status !== 'converted') {
+        // 结构化结果在 stdout；stderr 同时给出一条标准错误，便于只看退出码 / stderr 的调用方
+        (0, output_1.emitError)(new error_1.AppError(outcome.failure?.code ?? 'MIGRATE_FAILED', outcome.failure?.message ?? outcome.status, {
+            retryable: outcome.failure?.retryable ?? false,
+            next_actions: data.nextActions,
+        }));
+        process.exitCode = 1;
     }
-    (0, output_1.emit)({
-        data: {
-            from,
-            to: opts.to,
-            templateVersion,
-            appliedRules: results.map((r) => ({
-                type: r.rule.type,
-                action: r.action,
-                path: r.path,
-                detail: r.detail,
-            })),
-            ...summarizeResults(results),
-            followLatestPackages: followLatest,
-            installError,
-            devRestarted,
-            nextActions: (0, env_1.isSandboxEnv)()
-                ? [
-                    'git status / git diff 评估改动并 commit',
-                    'miaoda skills sync 同步到新 stack 的 agent skills',
-                ]
-                : [
-                    'git status / git diff 评估改动并 commit',
-                    '重启 dev 进程让新 scripts/dev.js + 新依赖生效:重跑 npm run dev(killOrphansByPort 会自动踢掉旧进程)',
-                    'miaoda skills sync 同步到新 stack 的 agent skills',
-                ],
-        },
-    });
 }
 /**
- * 从 tmp 端 template package.json 中删除 user 项目通常拥有的字段，避免 merge-json 时这些
- * 字段被 template 值覆盖。需要 strip 的字段以 npm 模板里"通常专属于具体应用"的为准。
+ * manual 调用（feida-ai 升级全栈 / html → design-html、本机手动执行）只是依赖没装上：结果仍是
+ * status=failed、install.status=failed，但退出码 0。这些调用方只看退出码：退出码非 0 时，升级全栈
+ * 照样切应用类型、却跳过它自己的 `npm install --force` 补装；design-html 不回写库里的 stack，
+ * 而下一轮读到已转换的 meta 又跳过迁移，库与沙箱永久不一致。文件已转换、依赖可补装，
+ * 按 0.1.46 的软失败交还调用方。平台调用（upgrade / history_restore）按结构化结果推进，保持严格。
  */
-function stripUserOwnedFields(pkgPath) {
-    if (!node_fs_1.default.existsSync(pkgPath))
-        return;
-    const json = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
-    const userOwned = [
-        'name',
-        'version',
-        'private',
-        'description',
-        'author',
-        'keywords',
-        'license',
-        'repository',
-        'homepage',
-        'bugs',
-    ];
-    let changed = false;
-    for (const key of userOwned) {
-        if (Reflect.deleteProperty(json, key))
-            changed = true;
+function isLenientInstallFailure(outcome) {
+    return (outcome.purpose === 'manual' &&
+        outcome.status === 'failed' &&
+        outcome.failure?.stage === 'install');
+}
+function toOutput(outcome, sandbox) {
+    return {
+        status: outcome.status,
+        mode: outcome.mode,
+        runId: outcome.runId,
+        purpose: outcome.purpose,
+        conflictPolicy: outcome.conflictPolicy,
+        operationRef: outcome.operationRef,
+        from: outcome.source.stack,
+        to: outcome.target.stack,
+        source: outcome.source,
+        target: outcome.target,
+        templateVersion: outcome.target.templateVersion,
+        stages: outcome.stages,
+        failure: outcome.failure,
+        warnings: outcome.warnings,
+        conflicts: outcome.conflicts,
+        overwritten: outcome.overwritten,
+        changes: outcome.changes,
+        appliedRules: outcome.results.map((r) => ({
+            type: r.rule.type,
+            action: r.action,
+            path: r.path,
+            detail: r.detail,
+        })),
+        ...summarizeResults(outcome.results),
+        followLatestPackages: outcome.followLatestPackages,
+        install: outcome.install,
+        installError: outcome.install.error,
+        verify: outcome.verify,
+        originalIntact: outcome.originalIntact,
+        restartSignalSent: outcome.restartSignalSent,
+        // 兼容旧字段：只表示发出了重启信号，不是健康结果
+        devRestarted: outcome.restartSignalSent,
+        readiness: outcome.readiness,
+        nextActions: nextActions(outcome, sandbox),
+    };
+}
+function nextActions(outcome, sandbox) {
+    if (outcome.status === 'conflict') {
+        return [
+            outcome.originalIntact
+                ? '按 conflicts 列出的路径 / ID 手动处理冲突（预检发现，工程未写入）'
+                : '按 conflicts 列出的路径 / ID 手动处理冲突；工程已有部分改动（见 changes），冲突文件未覆盖',
+            '处理后对同一工程重新执行 migrate --to 同一目标，按真实布局继续 / 修复',
+        ];
+    }
+    if (outcome.status === 'failed') {
+        if (outcome.originalIntact) {
+            return [`工程未写入；修复 ${outcome.failure?.stage ?? 'unknown'} 阶段问题后重试`];
+        }
+        return [
+            `${outcome.failure?.stage ?? 'unknown'} 阶段失败，现场保留在原目录（部分改动见 changes），不会自动回滚`,
+            '修复问题后对同一工程重新执行 migrate --to 同一目标，按真实布局修复并接续安装 / 构建',
+            '如需放弃本次转换，由调用方按代码版本（如 git）恢复原工程',
+        ];
+    }
+    const policyActions = [];
+    if (outcome.overwritten.length > 0) {
+        policyActions.push('overwritten 列出的用户改动已被模板替换：用 git diff 核对，需要保留的业务改动从 git 历史手动合回');
     }
-    if (changed) {
-        node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(json, null, 2) + '\n');
+    if (outcome.warnings.some((w) => w.code === 'MIGRATE_CONFLICT_KEPT')) {
+        policyActions.push('warnings 中 MIGRATE_CONFLICT_KEPT 的位置保留了用户内容、未按目标 stack 适配，按需手动调整');
     }
+    return sandbox
+        ? [
+            ...policyActions,
+            '调用方核验沙箱 dev 进程与预览 readiness（restartSignalSent 只表示发出了重启信号）',
+            'git status / git diff 评估改动并 commit',
+            'miaoda skills sync 同步到新 stack 的 agent skills',
+        ]
+        : [
+            ...policyActions,
+            '重启 dev 进程让新 scripts/dev.js + 新依赖生效：重跑 npm run dev，并验证预览',
+            'git status / git diff 评估改动并 commit',
+            'miaoda skills sync 同步到新 stack 的 agent skills',
+        ];
 }
 function summarizeResults(results) {
     const moved = [];
@@ -270,6 +188,7 @@ function summarizeResults(results) {
                 break;
             case 'appended':
             case 'noop':
+            case 'conflict':
                 break;
         }
     }

package/dist/cli/handlers/app/sync.js

@@ -18,6 +18,7 @@ const githooks_1 = require("../../../utils/githooks");
 const logs_dir_1 = require("../../../utils/logs-dir");
 const install_1 = require("../../../services/app/init/install");
 const spark_meta_1 = require("../../../utils/spark-meta");
+const engineering_state_1 = require("../../../utils/engineering-state");
 const run_npm_1 = require("../../../utils/run-npm");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
@@ -46,7 +47,7 @@ const MANAGED_PLATFORM_PACKAGES = {
     '@lark-apaas/http-client': 'latest',
 };
 /**
- * miaoda app sync [--dir <path>]
+ * miaoda app sync [--dir <path>] [--strict]
  *
  * 一站式同步：把当前 stack 的 sync 规则全套 apply 到 user app，对齐沙箱里
  * `npm run upgrade → npx fullstack-cli sync` 的行为，并补 miaoda-cli 本地开发独有规则。
@@ -68,7 +69,8 @@ const MANAGED_PLATFORM_PACKAGES = {
 async function handleAppSync(opts) {
     await Promise.resolve();
     const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+    // 严格读：meta 损坏时报 SPARK_META_CORRUPT，不当成空对象继续
+    const meta = (0, spark_meta_1.readSparkMetaStrict)(targetDir) ?? {};
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('SYNC_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
     }
@@ -106,7 +108,9 @@ async function handleAppSync(opts) {
     (0, logs_dir_1.ensureLogsDir)(targetDir);
     // 3. snapshot 当前 user app 装的管控包版本，供 install 后 diff 用
     const beforeSpecs = snapshotManagedDepSpecs(targetDir);
-    // 4. npm install —— 跟 init 一样软失败,install 挂了不该阻断 emit / sync 总结输出。
+    // 4. npm install —— 失败时仍输出完整的规则应用结果，status=failed，不把"文件同步了、依赖没装上"
+    //    报成成功；已应用的规则保留（规则幂等，重跑 sync 补齐）。只有 --strict 以退出码 1 结束：
+    //    dev.sh 与 lark-cli `+init` 不带 --strict，后者按退出码判成败，安装抖动不能让它整条失败。
     // 把 user app 装着的**所有**管控包显式作为 `<pkg>@latest` 位置参数传给 npm install:
     //   - npm 自然会把 spec 改写成 ^具体最新版,lockfile 同步更新 → 不需要 sync 主动改 spec
     //   - 没装的管控包不动 (sync 的职责是对齐,不是塞依赖)
@@ -134,20 +138,53 @@ async function handleAppSync(opts) {
     }
     catch (err) {
         installError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('sync', `⚠ npm install failed (continuing): ${installError}`);
+        (0, logger_1.log)('sync', opts.strict
+            ? `✗ npm install failed: ${installError}`
+            : `⚠ npm install failed (continuing): ${installError}`);
     }
     // 5. install 之后再读一次 package.json，diff 出 npm 实际改写的 spec
     const afterSpecs = snapshotManagedDepSpecs(targetDir);
     const upgradedPackages = diffManagedSpecs(beforeSpecs, afterSpecs, 'sync');
+    const failed = installError !== undefined;
+    recordSyncState(targetDir, meta.stack, installError);
     (0, output_1.emit)({
         data: {
             stack: meta.stack,
+            status: failed ? 'failed' : 'succeeded',
+            failedStage: failed ? 'install' : undefined,
             ...summarizeSyncResults(syncResults),
             upgradedPackages,
             gitHooks: hookActivation.action,
             installError,
+            nextActions: failed
+                ? [
+                    '检查上方 npm 输出定位安装错误（网络 / registry / 依赖冲突），修复后重跑 miaoda app sync',
+                ]
+                : undefined,
         },
     });
+    if (failed && opts.strict) {
+        (0, output_1.emitError)(new error_1.AppError('SYNC_INSTALL_FAILED', `npm install failed: ${installError ?? ''}`, {
+            retryable: true,
+            next_actions: ['修复安装错误（网络 / registry / 依赖冲突）后重跑 miaoda app sync'],
+        }));
+        process.exitCode = 1;
+    }
+}
+function recordSyncState(targetDir, stack, installError) {
+    try {
+        (0, engineering_state_1.writeEngineeringState)(targetDir, {
+            operation: 'sync',
+            status: installError === undefined ? 'succeeded' : 'failed',
+            stage: 'install',
+            code: installError === undefined ? undefined : 'SYNC_INSTALL_FAILED',
+            message: installError?.slice(0, 500),
+            toStack: stack,
+        });
+    }
+    catch (err) {
+        (0, logger_1.log)('sync', `⚠ failed to record engineering state: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /** 老命令 `miaoda app upgrade` 的 handler 名，保留为 sync handler 的 alias。 */
 exports.handleAppUpgrade = handleAppSync;

package/dist/config/fullstack-managed-files.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * nestjs-react-fullstack 工程里**明确由平台托管**的文件清单 —— sync 与 migrate 共用的 SSOT。
+ *
+ * 所有权用"本次会触及的明确清单"表达（不做通用三方合并、不补全量历史模板基线）：
+ *   - 清单内文件：按兼容模板版本整文件更新（同名覆盖）。
+ *   - 清单外文件：一律视为用户所有。scripts/ 下用户自建的 report.js 等额外文件不删除、不覆盖。
+ *
+ * 清单取自本仓 upgrade/templates/nestjs-react-fullstack/templates 下的 scripts/ 与 .githooks/。
+ * test/config/fullstack-managed-files 会校验 upgrade 模板目录与本清单一一对应 —— 模板新增托管脚本
+ * 必须同步加到这里，否则 CI 失败。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FULLSTACK_MANAGED_BUILD_DEV_DEPENDENCIES = exports.FULLSTACK_MANAGED_FILES = exports.FULLSTACK_MANAGED_HOOK_FILES = exports.FULLSTACK_MANAGED_SCRIPT_FILES = void 0;
+exports.managedFileRules = managedFileRules;
+exports.managedBuildDependencyRules = managedBuildDependencyRules;
+/** 平台托管的脚本（相对项目根） */
+exports.FULLSTACK_MANAGED_SCRIPT_FILES = [
+    'scripts/dev.sh',
+    'scripts/dev.js',
+    'scripts/dev-local.js',
+    'scripts/build.sh',
+    'scripts/run.sh',
+    'scripts/lint.js',
+    'scripts/prune-smart.js',
+    'scripts/hooks/run-precommit.js',
+];
+/** 平台托管的 git hook 入口（相对项目根） */
+exports.FULLSTACK_MANAGED_HOOK_FILES = ['.githooks/pre-commit'];
+/** 全部托管文件 */
+exports.FULLSTACK_MANAGED_FILES = [
+    ...exports.FULLSTACK_MANAGED_SCRIPT_FILES,
+    ...exports.FULLSTACK_MANAGED_HOOK_FILES,
+];
+/**
+ * 把托管清单展开成逐文件的 `file` 规则（overwrite=true）。
+ *
+ * 不用 `directory` 规则：directory 会把模板目录里**任何**文件都当托管文件同步过去，清单边界
+ * 由模板目录内容隐式决定；逐文件展开让"哪些文件归平台"显式可审。源文件缺失时规则返回
+ * skipped（模板与清单漂移由测试兜底）。
+ */
+function managedFileRules() {
+    return exports.FULLSTACK_MANAGED_FILES.map((file) => ({
+        type: 'file',
+        from: file,
+        to: file,
+        overwrite: true,
+    }));
+}
+/**
+ * 托管构建脚本的配套依赖：build.sh 的智能裁剪（prune-smart.js）require('@vercel/nft')，模板与
+ * 沙箱镜像都不提供它。迁移后的工程第一次完整构建（发布或本地 npm run build）会用到，所以
+ * migrate / repair 对未声明的工程补 devDependencies（版本为实测的 0.30.4）；已声明的用户版本
+ * 不降级、不覆盖。
+ */
+exports.FULLSTACK_MANAGED_BUILD_DEV_DEPENDENCIES = {
+    '@vercel/nft': '0.30.4',
+};
+/** 把托管构建依赖展开成 `ensure-dependency` 规则（缺失才补，已声明保持用户版本）。 */
+function managedBuildDependencyRules() {
+    return Object.entries(exports.FULLSTACK_MANAGED_BUILD_DEV_DEPENDENCIES).map(([name, version]) => ({
+        type: 'ensure-dependency',
+        name,
+        version,
+        section: 'devDependencies',
+    }));
+}

package/dist/config/migrate-configs/html-to-design-html.js

@@ -19,7 +19,7 @@
  *   - 不从 design-html template 拷任何文件（模板本身只有 _gitignore + package.json；
  *     用户已有的 .gitignore 是 html 版超集，保留无害）
  *   - 不动 README.md / .npmrc / .env —— 部署时均被 EXCLUDES 过滤
- *   - 不管 dev 进程 / MIAODA_APP_TYPE 切换（平台职责；沙箱 pkill 匹配的
+ *   - 不管 dev 进程 / MIAODA_APP_TYPE 切换（平台职责；沙箱重启信号匹配的
  *     scripts/dev.js 在 html 项目里不存在，自然跳过）
  *
  * handler 收尾的 npm install 照常跑：devserver 依赖删掉后重新生成精简 lockfile，

package/dist/config/migrate-configs/index.js

@@ -16,6 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMigrateConfig = getMigrateConfig;
+exports.getRepairConfig = getRepairConfig;
 exports.listSupportedMigrations = listSupportedMigrations;
 const vite_react_to_nestjs_react_fullstack_1 = __importDefault(require("./vite-react-to-nestjs-react-fullstack"));
 const html_to_design_html_1 = __importDefault(require("./html-to-design-html"));
@@ -28,6 +29,14 @@ const MIGRATE_REGISTRY = {
 function getMigrateConfig(from, to) {
     return MIGRATE_REGISTRY[`${from}:${to}`] ?? null;
 }
+/**
+ * 磁盘已是目标 stack 时（同目标重试、历史恢复后平台已新、旧版 CLI 半完成样本）用于 repair 的
+ * 配置：取第一条以 stack 为目标的迁移配置。规则本身对已转换工程幂等（源目录不存在即跳过、
+ * 定向适配已对齐即 noop），配合 repair 模式跳过 migrateOnly 规则。
+ */
+function getRepairConfig(stack) {
+    return Object.values(MIGRATE_REGISTRY).find((c) => c.to === stack) ?? null;
+}
 /** 列出已支持的迁移路径，给 handler / 命令 help 用 */
 function listSupportedMigrations() {
     return Object.keys(MIGRATE_REGISTRY).map((key) => {