@lark-apaas/miaoda-cli 0.1.37 → 0.1.39-alpha.0b274c0

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

@@ -15,6 +15,7 @@ const logs_dir_1 = require("../../../utils/logs-dir");
 const env_1 = require("../../../utils/env");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
+const engineering_state_1 = require("../../../utils/engineering-state");
 /**
  * miaoda app init
  *
@@ -32,24 +33,54 @@ const output_1 = require("../../../utils/output");
  * 的版本（没经 sync 覆盖）；首次 install 装的也是 template 钉的版本（没升 latest），
  * package.json 跟 template 完全一致。dev.sh 入口的 sync 会修正这些 drift。
  *
- * 幂等：.spark/meta.json 存在即表示已完整成功一次，直接退出，不重跑任何子步骤。
+ * 幂等：.spark/meta.json 存在时不重跑渲染 / 安装（不覆盖业务代码），但会做只读就绪核验并输出
+ * ready / problems —— meta 存在不等于就绪；--strict 时未就绪退出码 1。
  * 半渲染状态（package.json 在但 meta.json 不在）会重新跑完整流程。
+ *
+ * 同步安装失败是失败：meta 仍写出（脚手架已渲染，避免重跑覆盖已开始编辑的文件），本地执行
+ * 记录标为失败，输出 status=failed / failedStage=install 并退出码 1。
  */
 async function handleAppInit(opts) {
     await Promise.resolve();
     const targetDir = opts.targetDir ?? process.cwd();
     const metaPath = node_path_1.default.join(targetDir, '.spark', 'meta.json');
     if (node_fs_1.default.existsSync(metaPath)) {
+        let expectedStack;
+        if (opts.template || opts.appType) {
+            try {
+                expectedStack = (0, index_1.resolveStack)({ template: opts.template, appType: opts.appType });
+            }
+            catch (err) {
+                // 非严格调用保持历史行为：已初始化时不因参数校验失败而报错
+                if (opts.strict)
+                    throw err;
+            }
+        }
+        const check = (0, index_1.checkWorkspaceReady)({ targetDir, expectedStack });
         if (!(0, output_1.isJsonMode)()) {
             process.stdout.write(`Already initialized: ${metaPath}\n`);
+            for (const p of check.problems) {
+                process.stdout.write(`  ✗ ${p.code}: ${p.message}\n`);
+            }
         }
         (0, output_1.emit)({
             data: {
                 initialized: false,
                 reason: 'already_initialized',
                 targetDir,
+                stack: check.stack,
+                ready: check.ready,
+                problems: check.problems,
             },
         });
+        if (opts.strict && !check.ready) {
+            (0, output_1.emitError)(new error_1.AppError('WORKSPACE_NOT_READY', check.problems.map((p) => `${p.code}: ${p.message}`).join('; '), {
+                next_actions: [
+                    '按 problems 修复：依赖 / 文件问题执行 miaoda app sync，布局不符执行 miaoda app migrate',
+                ],
+            }));
+            process.exitCode = 1;
+        }
         return;
     }
     const stack = (0, index_1.resolveStack)({ template: opts.template, appType: opts.appType });
@@ -130,21 +161,29 @@ async function handleAppInit(opts) {
         app_id: opts.appId,
     });
     // async 模式：meta 已落盘（= 脚手架就绪），再派发后台安装并立即返回（不等装完）。
+    // 执行记录先标 running，后台 worker 结束时改写为 succeeded / failed；中断则停留在 running。
     let asyncDispatch;
     if (opts.asyncInstall) {
+        recordInitState(targetDir, 'running', 'install');
         asyncDispatch = (0, index_1.dispatchAsyncInstall)({ targetDir });
     }
+    const installFailed = installResult?.source === 'failed';
+    if (installResult !== undefined) {
+        recordInitState(targetDir, installFailed ? 'failed' : 'succeeded', installResult.source === 'skipped' ? 'install-skipped' : 'install', installResult.error);
+    }
     if (!(0, output_1.isJsonMode)()) {
         if (opts.asyncInstall && asyncDispatch) {
             process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install dispatched in background pid ${String(asyncDispatch.pid)}) in ${targetDir}\n`);
         }
         else if (installResult) {
-            process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+            process.stdout.write(`${installFailed ? '✗' : '✓'} Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
         }
     }
     (0, output_1.emit)({
         data: {
             initialized: true,
+            status: installFailed ? 'failed' : 'succeeded',
+            failedStage: installFailed ? 'install' : undefined,
             template: stack,
             templatePackage: tplResult.packageName,
             templateVersion: tplResult.version,
@@ -177,8 +216,34 @@ async function handleAppInit(opts) {
                     cacheZip: installResult?.cacheZip,
                     installError: installResult?.error,
                 }),
+            nextActions: installFailed
+                ? [
+                    '检查 npm 输出定位安装错误（网络 / registry / 依赖冲突），修复后执行 miaoda app sync 补装依赖',
+                ]
+                : undefined,
         },
     });
+    if (installFailed) {
+        (0, output_1.emitError)(new error_1.AppError('INIT_INSTALL_FAILED', `npm install failed: ${installResult?.error ?? ''}`, {
+            retryable: true,
+            next_actions: ['修复安装错误后执行 miaoda app sync 补装依赖'],
+        }));
+        process.exitCode = 1;
+    }
+}
+function recordInitState(targetDir, status, stage, error) {
+    try {
+        (0, engineering_state_1.writeEngineeringState)(targetDir, {
+            operation: 'init',
+            status,
+            stage,
+            code: status === 'failed' ? 'INIT_INSTALL_FAILED' : undefined,
+            message: error?.slice(0, 500),
+        });
+    }
+    catch (err) {
+        (0, logger_1.log)('init', `⚠ failed to record engineering state: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /**
  * 处理 --source-path 导入：当前仅 app_type=modern_html 生效。

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

@@ -4,236 +4,127 @@ 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 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：原目录内文件适配、依赖安装、严格验证（全栈为完整构建）全部完成。
+ *     运行 readiness 不在 CLI 内判定（readiness.status=pending_caller_verification）——
+ *     沙箱里 restartSignalSent / devRestarted 只表示发出了 pkill 重启信号，不是健康结果。
+ *   status=conflict：存在无法确定性处理的冲突（conflicts 给出具体路径 / ID），冲突文件不覆盖；
+ *     预检阶段发现时工程未写入（originalIntact=true），应用阶段发现时可能已有部分改动。
+ *   status=failed：某阶段失败（failure.stage / code），现场原样保留、不自动回滚；
+ *     originalIntact=true 仅表示失败发生在任何工程写入之前。
+ *   非 converted 一律退出码 1。
  *
- * 执行流：
- *   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, node_child_process_1.execFileSync)('npm', 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)}`);
-            }
-        }
-    }
-    // 沙箱环境下重启 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 吞掉
-    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 没在跑)
-        }
-    }
-    (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',
-                ],
-        },
+    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 (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;
+    }
 }
-/**
- * 从 tmp 端 template package.json 中删除 user 项目通常拥有的字段，避免 merge-json 时这些
- * 字段被 template 值覆盖。需要 strip 的字段以 npm 模板里"通常专属于具体应用"的为准。
- */
-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 toOutput(outcome, sandbox) {
+    return {
+        status: outcome.status,
+        mode: outcome.mode,
+        runId: outcome.runId,
+        purpose: outcome.purpose,
+        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,
+        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 (changed) {
-        node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(json, null, 2) + '\n');
+    if (outcome.status === 'failed') {
+        if (outcome.originalIntact) {
+            return [`工程未写入；修复 ${outcome.failure?.stage ?? 'unknown'} 阶段问题后重试`];
+        }
+        return [
+            `${outcome.failure?.stage ?? 'unknown'} 阶段失败，现场保留在原目录（部分改动见 changes），不会自动回滚`,
+            '修复问题后对同一工程重新执行 migrate --to 同一目标，按真实布局修复并接续安装 / 构建',
+            '如需放弃本次转换，由调用方按代码版本（如 git）恢复原工程',
+        ];
     }
+    return sandbox
+        ? [
+            '调用方核验沙箱 dev 进程与预览 readiness（restartSignalSent 只表示发出了重启信号）',
+            'git status / git diff 评估改动并 commit',
+            'miaoda skills sync 同步到新 stack 的 agent skills',
+        ]
+        : [
+            '重启 dev 进程让新 scripts/dev.js + 新依赖生效：重跑 npm run dev，并验证预览',
+            'git status / git diff 评估改动并 commit',
+            'miaoda skills sync 同步到新 stack 的 agent skills',
+        ];
 }
 function summarizeResults(results) {
     const moved = [];
@@ -267,6 +158,7 @@ function summarizeResults(results) {
                 break;
             case 'appended':
             case 'noop':
+            case 'conflict':
                 break;
         }
     }

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

@@ -9,7 +9,6 @@ exports.runStackSync = runStackSync;
 exports.summarizeSyncResults = summarizeSyncResults;
 exports.snapshotManagedDepSpecs = snapshotManagedDepSpecs;
 exports.diffManagedSpecs = diffManagedSpecs;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const sync_configs_1 = require("../../../config/sync-configs");
@@ -19,6 +18,8 @@ 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");
 const logger_1 = require("../../../utils/logger");
@@ -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,8 @@ 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 + 退出码 1，
+    //    不把"文件同步了、依赖没装上"报成成功。已应用的规则保留（规则幂等，重跑 sync 补齐）。
     // 把 user app 装着的**所有**管控包显式作为 `<pkg>@latest` 位置参数传给 npm install:
     //   - npm 自然会把 spec 改写成 ^具体最新版,lockfile 同步更新 → 不需要 sync 主动改 spec
     //   - 没装的管控包不动 (sync 的职责是对齐,不是塞依赖)
@@ -127,27 +130,58 @@ async function handleAppSync(opts) {
     (0, logger_1.log)('sync', `Running npm ${installArgs.join(' ')}...`);
     let installError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
+        (0, run_npm_1.execNpmSync)(installArgs, {
             cwd: targetDir,
             stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
         });
     }
     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', `✗ npm install failed: ${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) {
+        (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/cli/handlers/db/sql.js

@@ -47,7 +47,7 @@ const colors_1 = require("../../../utils/colors");
 const fuzzy_match_1 = require("../../../utils/fuzzy-match");
 const index_1 = require("../../../api/db/index");
 const sql_keywords_1 = require("../../../api/db/sql-keywords");
-const node_child_process_1 = require("node:child_process");
+const run_npm_1 = require("../../../utils/run-npm");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 /**
@@ -140,20 +140,22 @@ async function maybeSyncAgentSchema(results) {
     (0, logger_1.debug)(`[db sql] DDL detected, running \`npm run gen:db-schema\` in ${projectRoot}`);
     try {
         await new Promise((resolve) => {
-            const proc = (0, node_child_process_1.spawn)('npm', ['run', 'gen:db-schema'], {
+            const proc = (0, run_npm_1.spawnNpm)(['run', 'gen:db-schema'], {
                 stdio: ['ignore', 'pipe', 'pipe'],
                 cwd: projectRoot,
             });
             // --verbose：实时透传到 stderr 看进度；默认完全静默丢弃。
             // 任何路径下子进程输出都不会进入当前 CLI 的 stdout，--json 模式安全。
             // 注：默认路径必须 attach 监听器，否则 pipe 缓冲区写满会反压子进程。
+            // `?.`：stdio 走数组形式时 node 类型上 stdout/stderr 可为 null。这里 fd1/fd2
+            // 显式给了 'pipe'，实际恒非 null；真为 null 也意味着不是 pipe、不存在缓冲反压。
             if (verbose) {
-                proc.stdout.pipe(process.stderr);
-                proc.stderr.pipe(process.stderr);
+                proc.stdout?.pipe(process.stderr);
+                proc.stderr?.pipe(process.stderr);
             }
             else {
-                proc.stdout.on('data', drainChunk);
-                proc.stderr.on('data', drainChunk);
+                proc.stdout?.on('data', drainChunk);
+                proc.stderr?.on('data', drainChunk);
             }
             let timedOut = false;
             const timer = setTimeout(() => {