@lark-apaas/miaoda-cli 0.1.16-beta.70f1b39 → 0.1.17-alpha.0

package/dist/cli/commands/app/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAppCommands = registerAppCommands;
+const commander_1 = require("commander");
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/app/index");
+const index_2 = require("../../../config/migrate-configs/index");
 const error_1 = require("../../../utils/error");
 function registerAppCommands(program, opts = {}) {
     const description = opts.includeInit
@@ -22,8 +24,49 @@ function registerAppCommands(program, opts = {}) {
     if (opts.includeInit) {
         registerAppInit(appCmd);
         registerAppSync(appCmd);
+        registerAppMigrate(appCmd);
     }
 }
+function registerAppMigrate(parent) {
+    const supportedDesc = (0, index_2.listSupportedMigrations)()
+        .map((m) => `${m.from} → ${m.to}`)
+        .join(', ');
+    // 渐进式披露：migrate 是给妙搭平台 / 用户主动触发的命令，**不暴露给 Agent**。
+    //   - `miaoda app -h` / `miaoda app help` 都不列出此命令
+    //   - 但 `miaoda app migrate --to xxx` 仍能直接调用（仅命令注册时打 hidden 标记，行为不变）
+    //   - `--help` 也不显示 ——commander hidden 命令仅显式 invoke 时才暴露
+    // 用 addCommand(cmd, { hidden: true }) 而非 parent.command(...)，因为 commander 13
+    // 的 fluent `.command()` 不支持设置 hidden。
+    const cmd = new commander_1.Command('migrate')
+        .description('跨 stack 原地迁移：按 MigrateConfig 全套 apply（move + delete + 模板覆盖 + 字段 merge + set-stack）')
+        .requiredOption('--to <stack>', '目标 stack 短名')
+        .option('--from <stack>', '源 stack；默认读 .spark/meta.json 当前 stack')
+        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .addHelpText('after', `
+已支持的迁移路径
+  ${supportedDesc || '(none)'}
+
+JSON 输出
+  {"data": {"from": "...", "to": "...",
+            "appliedRules": [{"type": "...", "action": "...", "path": "...", "detail": "..."}],
+            "moved": [...], "deleted": [...], "synced": [...], "merged": [...], "patched": [...],
+            "skipped": N,
+            "nextActions": [...]}}
+
+示例
+  $ miaoda app migrate --to nestjs-react-fullstack
+  $ miaoda app migrate --from vite-react --to nestjs-react-fullstack
+  $ miaoda app migrate --to nestjs-react-fullstack --dir /path/to/app
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleAppMigrate)({
+            dir: rawOpts.dir,
+            from: rawOpts.from,
+            to: rawOpts.to,
+        });
+    }));
+    parent.addCommand(cmd, { hidden: true });
+}
 function registerAppSync(parent) {
     const cmd = parent
         .command('sync')

package/dist/cli/commands/deploy/modern.js

@@ -16,6 +16,7 @@ function registerDeployCommandsModern(program) {
         .description('触发 modern 应用发布：本地构建 + 本地部署（preRelease + localPublish）')
         .option('--dir <path>', '项目目录', '.')
         .option('--skip-build', '跳过 build 步骤（已构建好时使用）', false)
+        .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID 两字段')
         .addHelpText('after', `
 不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
 
@@ -32,6 +33,12 @@ function registerDeployCommandsModern(program) {
   6. savePluginInstances（扫描 dist/output_capabilities/*.json 批量注册）
   7. finalizeLocalRelease(Finished|Failed)
 
+--conf（关联元信息透传）
+  值为 JSON string，只识别两个字段，其余 key 忽略：
+    checkPointVersion  关联的 checkpoint 版本
+    commitID           关联的代码 commit ID
+  两字段均可选；非法 JSON / 非对象 / 字段值非字符串会报错。
+
 JSON 输出（stdout）
   {"data": {"appId": "...", "version": <n>, "url": "...", "releaseID": "...", "preReleaseID": "..."}}
 
@@ -39,12 +46,14 @@ JSON 输出（stdout）
   $ miaoda deploy
   $ miaoda deploy --dir ./my-app
   $ miaoda deploy --skip-build
+  $ miaoda deploy --conf '{"checkPointVersion":"v3","commitID":"a1b2c3d"}'
 `);
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
         await (0, modern_1.handleDeployModern)({
             dir: rawOpts.dir ?? '.',
             appId: (0, shared_1.resolveAppId)({}),
             skipBuild: rawOpts.skipBuild,
+            conf: rawOpts.conf,
         });
     }));
 }

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_STACKS = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
@@ -10,6 +10,8 @@ Object.defineProperty(exports, "handleAppInit", { enumerable: true, get: functio
 var sync_1 = require("./sync");
 Object.defineProperty(exports, "handleAppSync", { enumerable: true, get: function () { return sync_1.handleAppSync; } });
 Object.defineProperty(exports, "handleAppUpgrade", { enumerable: true, get: function () { return sync_1.handleAppUpgrade; } });
+var migrate_1 = require("./migrate");
+Object.defineProperty(exports, "handleAppMigrate", { enumerable: true, get: function () { return migrate_1.handleAppMigrate; } });
 // commands 层渲染 help 时需要这份枚举；从 handler barrel 转发，避免 commands → services 越界
 var index_1 = require("../../../services/app/init/index");
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return index_1.SUPPORTED_STACKS; } });

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

@@ -0,0 +1,223 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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 error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const logger_1 = require("../../../utils/logger");
+/**
+ * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
+ *
+ * 跨 stack 原地迁移：把 user app 从源 stack（默认 .spark/meta.json 当前 stack）转到目标 stack。
+ * 同一个 git 仓库内进行，不动 git history，所有改动作为 working tree 变更体现，用户跑完后
+ * 自行 `git status` / `git diff` 评估并 commit。
+ *
+ * 跟 sync 的区别：sync 是同 stack 内的版本对齐，migrate 是跨 stack 切换（布局重排、依赖
+ * 集合切换、配置文件全套替换）。两条命令的 rule 引擎共享（applyMigrateRules 内部对
+ * SyncRule 委派给 applySyncRules）。
+ *
+ * 执行流：
+ *   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）
+ */
+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',
+        });
+    }
+    catch (err) {
+        installError = err instanceof Error ? err.message : String(err);
+        (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
+    }
+    (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,
+            nextActions: [
+                'git status / git diff 评估改动并 commit',
+                'miaoda skills sync 同步到新 stack 的 agent skills',
+            ],
+        },
+    });
+}
+/**
+ * 从 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;
+    }
+    if (changed) {
+        node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(json, null, 2) + '\n');
+    }
+}
+function summarizeResults(results) {
+    const moved = [];
+    const deleted = [];
+    const synced = [];
+    const merged = [];
+    const patched = [];
+    let skipped = 0;
+    for (const r of results) {
+        if (r.path === undefined)
+            continue;
+        switch (r.action) {
+            case 'moved':
+                moved.push(r.path);
+                break;
+            case 'deleted':
+                deleted.push(r.path);
+                break;
+            case 'synced':
+            case 'created':
+                synced.push(r.path);
+                break;
+            case 'merged':
+                merged.push(r.path);
+                break;
+            case 'patched':
+                patched.push(r.path);
+                break;
+            case 'skipped':
+                skipped++;
+                break;
+            case 'appended':
+            case 'noop':
+                break;
+        }
+    }
+    return { moved, deleted, synced, merged, patched, skipped };
+}

package/dist/cli/handlers/deploy/modern.js

@@ -3,10 +3,46 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDeployConf = parseDeployConf;
 exports.handleDeployModern = handleDeployModern;
 const node_path_1 = __importDefault(require("node:path"));
 const output_1 = require("../../../utils/output");
+const error_1 = require("../../../utils/error");
 const index_1 = require("../../../services/deploy/modern/index");
+const CONF_EXPECTED = '期望形如 {"checkPointVersion":"...","commitID":"..."} 的 JSON 对象';
+/**
+ * 解析 `--conf` JSON string，只取 checkPointVersion / commitID 两个白名单字段。
+ * - 未传 → 返回 {}（行为不变）。
+ * - 非法 JSON / 非 object / 字段值非 string → 抛 DEPLOY_CONF_INVALID。
+ * - 空串字段视为未提供（不进 body，保持可选语义）；未知 key 忽略。
+ */
+function parseDeployConf(raw) {
+    if (raw === undefined || raw === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new error_1.AppError('DEPLOY_CONF_INVALID', `--conf 不是合法 JSON，${CONF_EXPECTED}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new error_1.AppError('DEPLOY_CONF_INVALID', `--conf 必须是 JSON 对象，${CONF_EXPECTED}`);
+    }
+    const source = parsed;
+    const conf = {};
+    for (const key of ['checkPointVersion', 'commitID']) {
+        const value = source[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string') {
+            throw new error_1.AppError('DEPLOY_CONF_INVALID', `--conf.${key} 必须是字符串，${CONF_EXPECTED}`);
+        }
+        if (value !== '')
+            conf[key] = value;
+    }
+    return conf;
+}
 /**
  * miaoda deploy（modern scene 专用，CLI 表面对齐 openclaw-cli）
  *
@@ -14,10 +50,13 @@ const index_1 = require("../../../services/deploy/modern/index");
  */
 async function handleDeployModern(opts) {
     const projectDir = node_path_1.default.resolve(opts.dir);
+    const conf = parseDeployConf(opts.conf);
     const result = await (0, index_1.runModernDeploy)({
         projectDir,
         appId: opts.appId,
         skipBuild: opts.skipBuild ?? false,
+        checkPointVersion: conf.checkPointVersion,
+        commitID: conf.commitID,
     });
     (0, output_1.emit)({
         data: {

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

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * 跨 stack 迁移注册表 —— 按 (from, to) 二元组查找对应的 MigrateConfig。
+ *
+ * 跟 sync 注册表 (src/config/sync-configs/index.ts) 的关系：sync 一份配置对应一个 stack，
+ * migrate 一份配置对应 (源 stack, 目标 stack) 二元组；模板资产 migrate 在 runtime 从 npm
+ * 拉目标 stack 的 template tarball（init 用同一套 renderTemplate），不再用 upgrade/templates/
+ * 的子集。
+ *
+ * 新增迁移路径：
+ *   1. src/config/migrate-configs/<from>-to-<to>.ts 里 export default MIGRATE_CONFIG
+ *   2. 在 MIGRATE_REGISTRY 加一条
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMigrateConfig = getMigrateConfig;
+exports.listSupportedMigrations = listSupportedMigrations;
+const vite_react_to_nestjs_react_fullstack_1 = __importDefault(require("./vite-react-to-nestjs-react-fullstack"));
+/** key 格式：`<from>:<to>` */
+const MIGRATE_REGISTRY = {
+    'vite-react:nestjs-react-fullstack': vite_react_to_nestjs_react_fullstack_1.default,
+};
+/** 返回 (from, to) 对应的 MigrateConfig；未注册时返回 null。 */
+function getMigrateConfig(from, to) {
+    return MIGRATE_REGISTRY[`${from}:${to}`] ?? null;
+}
+/** 列出已支持的迁移路径，给 handler / 命令 help 用 */
+function listSupportedMigrations() {
+    return Object.keys(MIGRATE_REGISTRY).map((key) => {
+        const [from, to] = key.split(':');
+        return { from, to };
+    });
+}

package/dist/config/migrate-configs/vite-react-to-nestjs-react-fullstack.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * vite-react → nestjs-react-fullstack 的跨 stack 迁移规则。
+ *
+ * 设计原则：**最小改动**。只动 fullstack 形态必须的文件 / package.json key，user 已有
+ * 的 vite.config / tsconfig / eslint / prettier / tailwind / postcss / components.json
+ * 等业务配置一律**保留**，不被 template 整体覆盖。
+ *
+ * 步骤：
+ *   1. src/ public/ 搬到 client/ 下（fullstack 布局）
+ *   2. 清掉 vite-react 时代的根 index.html / eslint.config.mjs / package-lock.json
+ *   3. 删 user package.json 里 lite SDK 相关 key（保留 coding-preset-vite-react）
+ *   4. 把 NestJS server runtime 拷进来（server/ + nest-cli.json + tsconfig.node.json
+ *      + client/index.html 等 fullstack 形态新增的资产）
+ *   5. 把 fullstack 必需的 scripts 加到 package.json（dev / build / type:check 等）
+ *   6. 从 fullstack template/package.json 取版本号，精确加 NestJS 强依赖白名单
+ *      （client-toolkit + 几个 @nestjs/* + fullstack-nestjs-core + hbs 等；不全量 merge）
+ *   7. codemod 业务代码：@lark-apaas/client-toolkit-lite → @lark-apaas/client-toolkit
+ *   8. codemod vite.config：defineConfig(...) → defineConfig(..., { fullstack: true })，
+ *      让 coding-preset-vite-react 启用 fullstack dev-proxy / html-output / basename /
+ *      server-log 4 件套，vite 8080 反代 HTML / API 到 nest 3000
+ *   9. set-stack 切 .spark/meta.json
+ *
+ * 跟 SDK 的协作：client-toolkit@1.2.52+ 顶层 single-entry 完整 re-export 了
+ * client-toolkit-lite 全部 48 项 API（fullstack-plugin#1124），所以 codemod 只换
+ * 包名、specifier 列表不动就够。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATE_CONFIG = void 0;
+exports.MIGRATE_CONFIG = {
+    from: 'vite-react',
+    to: 'nestjs-react-fullstack',
+    rules: [
+        // ===== 1. 用户领地搬迁 =====
+        { type: 'move-directory', from: 'src', to: 'client/src' },
+        { type: 'move-directory', from: 'public', to: 'client/public' },
+        // shared/ 不动（两边布局相同）；.env / .spark_project 同理。
+        // ===== 2. 清理 vite-react 残留 =====
+        // 根 index.html 被 client/index.html 取代（fullstack 用 HBS 渲染）
+        { type: 'delete-file', to: 'index.html' },
+        // ESLint 9 flat config 文件名变了（user eslint.config.mjs → eslint.config.js）
+        { type: 'delete-file', to: 'eslint.config.mjs' },
+        // 依赖集合变了，lockfile 重新生成
+        { type: 'delete-file', to: 'package-lock.json' },
+        // ===== 3. 从 user package.json 删 vite-react 专属字段 =====
+        // 注意保留 devDependencies.@lark-apaas/coding-preset-vite-react —— user 迁移后
+        // vite.config 仍用它（开 fullstack 模式即可），不切到 fullstack-vite-preset。
+        {
+            type: 'delete-json-keys',
+            to: 'package.json',
+            keys: [
+                // 顶层 "type": "module" —— vite-react ESM 入口约定，nestjs CommonJS 不需要
+                'type',
+                // lite SDK：codemod 后 import 走 client-toolkit 顶层
+                'dependencies.@lark-apaas/client-toolkit-lite',
+            ],
+        },
+        // ===== 4. fullstack 形态必需资产（覆盖 user 已有同名文件） =====
+        // server/ 整目录：main.ts / app.module.ts / common/ / modules/view/ 等（fullstack 必需）
+        { type: 'directory', from: 'server', to: 'server', overwrite: true },
+        // nest-cli.json：nest build 入口
+        { type: 'file', from: 'nest-cli.json', to: 'nest-cli.json', overwrite: true },
+        // tsconfig.* —— vite-react 时代 tsconfig 配 include: ["src"]，迁完代码搬到 client/src，
+        // include 路径不对 + 老 tsconfig.app 还 extends @lark-apaas/coding-presets-react；
+        // 整体覆盖到 fullstack 版本（include 改 client/** + shared/**、extends fullstack-presets）。
+        // user 自己加的 paths / strict 等设置如有需要，按 git diff 手动加回。
+        { type: 'file', from: 'tsconfig.json', to: 'tsconfig.json', overwrite: true },
+        { type: 'file', from: 'tsconfig.app.json', to: 'tsconfig.app.json', overwrite: true },
+        { type: 'file', from: 'tsconfig.node.json', to: 'tsconfig.node.json', overwrite: true },
+        // ESLint 9 flat config —— vite-react 用 eslint.config.mjs 已删，fullstack 用
+        // eslint.config.js (commonjs) + extends @lark-apaas/fullstack-presets；user 通常不改
+        { type: 'file', from: 'eslint.config.js', to: 'eslint.config.js', overwrite: true },
+        // client/index.html：HBS 模板（fullstack 用，vite-react 用根 index.html 已删）
+        { type: 'file', from: 'client/index.html', to: 'client/index.html', overwrite: true },
+        // scripts/ 整目录：fullstack 形态启动 / 构建 / lint 所需的 8 个平台脚本（dev.sh /
+        // dev.js / dev-local.js / build.sh / lint.js / prune-smart.js / run.sh / hooks/）。
+        // dev.sh exec node dev.js，dev.js 才是并发起 nest + vite 的核心 —— 漏一个 dev 跑不起来。
+        // overwrite: true：这些脚本由平台 cli 维护，user 一般不改；按 fullstack 版本覆盖。
+        { type: 'directory', from: 'scripts', to: 'scripts', overwrite: true },
+        // .githooks（fallback，user 已有则保留）
+        { type: 'directory', from: '.githooks', to: '.githooks', overwrite: false },
+        // shared/ fallback（user 已有同名文件保留，template 新增文件加入）
+        { type: 'directory', from: 'shared', to: 'shared', overwrite: false },
+        // .env fallback（user 没有时用 template 默认）
+        { type: 'file', from: '.env', to: '.env', overwrite: false },
+        // ===== 5. 加 fullstack 形态必需的 scripts =====
+        // 这些 scripts 用 user 现有的可能性低（vite-react 没有 nest 相关 script），直接覆盖
+        {
+            type: 'add-script',
+            name: 'dev',
+            command: './scripts/dev.sh',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'dev:server',
+            command: 'NODE_ENV=development nest start --watch',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'dev:client',
+            command: 'NODE_ENV=development vite --config vite.config.ts',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build',
+            command: './scripts/build.sh',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build:server',
+            command: 'NODE_ENV=production nest build',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build:client',
+            command: 'NODE_ENV=production vite build --config vite.config.ts',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build:prod',
+            command: 'npm run build:server && npm run build:client',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'start',
+            command: 'NODE_ENV=production node main.js',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'type:check:server',
+            command: 'tsc --noEmit --project tsconfig.node.json',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'type:check:client',
+            command: 'tsc --noEmit --project tsconfig.app.json',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'type:check',
+            command: 'concurrently -n "server,client" -c "blue,green" "npm run type:check:server" "npm run type:check:client"',
+            overwrite: true,
+        },
+        // ----- 平台脚本调用链 -----
+        // build.sh 步骤 1 跑 `npm run gen:openapi`,缺这条 npm ERR missing script,build 直接挂。
+        // scripts/lint.js 内部 spawn `npm run eslint` 和 `npm run stylelint`,缺这两条 lint 挂。
+        // 这些都是 fullstack 平台脚本自洽必需的桥接 script,user 不会自定义,直接覆盖。
+        {
+            type: 'add-script',
+            name: 'gen:openapi',
+            command: "echo 'UNSUPPORTED, SKIP'",
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'gen:db-schema',
+            command: 'npx -y @lark-apaas/db-schema-sync@latest --output server/database/schema.ts --export-custom-types',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'eslint',
+            command: 'eslint . --quiet',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'stylelint',
+            command: 'stylelint client/src/**/*.css --quiet',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'lint',
+            command: 'node ./scripts/lint.js',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'precommit',
+            command: 'node scripts/hooks/run-precommit.js',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'upgrade',
+            command: 'npx -y @lark-apaas/fullstack-cli sync --disable-gen-openapi',
+            overwrite: true,
+        },
+        // ----- user 可能自定义的 scripts -----
+        // format/test 多半 user 自己改过(prettier 配 / jest 配),保留 user 自有值。
+        {
+            type: 'add-script',
+            name: 'format',
+            command: 'prettier --write "{server,client,test}/**/*.{js,ts,tsx,json,md}"',
+            overwrite: false,
+        },
+        {
+            type: 'add-script',
+            name: 'test',
+            command: 'jest',
+            overwrite: false,
+        },
+        {
+            type: 'add-script',
+            name: 'test:watch',
+            command: 'jest --watch',
+            overwrite: false,
+        },
+        {
+            type: 'add-script',
+            name: 'test:e2e',
+            command: 'jest --config test/e2e/jest.config.js',
+            overwrite: false,
+        },
+        // ===== 6. 从 fullstack template 取版本号加 NestJS 强依赖（精确白名单） =====
+        // 不走 merge-json（template 130+ devDeps 全 merge 会污染 user 业务依赖集合）；
+        // 白名单只列 fullstack 启动能跑起来必需的最小集。
+        {
+            type: 'add-deps-from-template',
+            from: 'package.json',
+            to: 'package.json',
+            dependencies: [
+                // NestJS server 核心
+                '@nestjs/core',
+                '@nestjs/common',
+                '@nestjs/platform-express',
+                '@nestjs/config',
+                '@nestjs/axios',
+                '@nestjs/swagger',
+                // 妙搭 fullstack server SDK（main.ts / view module 等都依赖）
+                '@lark-apaas/fullstack-nestjs-core',
+                // HBS 模板引擎（client/index.html 渲染）
+                'hbs',
+                // NestJS runtime 必需
+                'reflect-metadata',
+                'rxjs',
+                'tslib',
+                // DTO 校验 / 转换
+                'class-transformer',
+                'class-validator',
+                // .env 加载（scripts/dev.sh 用到 dotenv-cli 风格）
+                'dotenv',
+                // client-toolkit：替代 lite，业务代码 codemod 后走它
+                '@lark-apaas/client-toolkit',
+            ],
+            devDependencies: [
+                // nest start / nest build 必需
+                '@nestjs/cli',
+                '@nestjs/testing',
+                // server ts 编译
+                'ts-node',
+                '@types/express',
+                '@types/hbs',
+                '@types/node',
+                // 并发跑 nest + vite（scripts/dev.sh 用 concurrently）
+                'concurrently',
+                // fullstack server 端 tsconfig.node.json 通过 extends 引这个包
+                // （@lark-apaas/fullstack-presets/lib/simple/tsconfig/tsconfig.node.json）;
+                // 不装会导致 nest build / type:check:server / vite dev 解析 tsconfig 时 ENOENT
+                '@lark-apaas/fullstack-presets',
+            ],
+        },
+        // ===== 7. 业务代码 codemod：lite → client-toolkit 包名替换 =====
+        // client-toolkit@1.2.52+ 顶层完整 re-export lite 全部 48 项，specifier 列表不动。
+        // 同时扫 shared/（client/server 共享代码也可能引 lite 类型 / utils）。
+        { type: 'codemod-client-toolkit-lite', root: 'client/src' },
+        { type: 'codemod-client-toolkit-lite', root: 'shared' },
+        // ===== 8. vite.config codemod：加 { fullstack: true } 第二参 =====
+        // user vite.config 现在是 defineConfig({...}) 单参；fullstack 形态需要 vite 8080
+        // 反代 HTML / API 到 nest 3000，coding-preset-vite-react 用 fullstack option 启用
+        // 这一行为（详见 fullstack-plugin coding-preset-vite-react#fullstack）。
+        { type: 'codemod-vite-config-fullstack', to: 'vite.config.ts' },
+        // ===== 9. 切 stack =====
+        { type: 'set-stack', stack: 'nestjs-react-fullstack' },
+    ],
+    // install 收尾要钉 latest 的关键平台包 —— 见 MigrateConfig.followLatestPackages 注释。
+    //   - client-toolkit：codemod 后业务代码依赖 lite 兼容 API（getCurrentUserProfile 等），
+    //     这些 API 当前只在 alpha 版本里。template caret range 不匹配 pre-release，必须显式 latest。
+    //   - coding-preset-vite-react：本次切到 MIAODA_APP_TYPE='3' env 检测，老版本 preset 不认 env。
+    followLatestPackages: ['@lark-apaas/client-toolkit', '@lark-apaas/coding-preset-vite-react'],
+};
+exports.default = exports.MIGRATE_CONFIG;

package/dist/config/migrate.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * MigrateRule 类型定义 —— miaoda app migrate（跨 stack 迁移）的核心抽象。
+ *
+ * 跟 sync 的关系：sync 是**同 stack 内**的版本同步（脚手架更新、平台依赖钉版本）；
+ * migrate 是**跨 stack 切换**（如 vite-react → nestjs-react-fullstack）。
+ *
+ * 复用：MigrateRule 把 SyncRule 全部纳入联合类型（10 种）—— migrate 也要做覆盖 / 删除 /
+ * merge-json / patch-script 等动作，没必要重新定义。
+ *
+ * 新增：MoveRule 和 SetStackRule 是 migrate 专有的语义，sync 用不上：
+ *   - MoveRule：把用户领地从老布局搬到新布局（如 src/ → client/src/），完成后源消失。
+ *   - SetStackRule：把 .spark/meta.json 的 stack 字段切到新 stack，migrate 必跑的收尾。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/app/init/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.TEMPLATE_PACKAGE_BY_STACK = exports.SUPPORTED_STACKS = exports.renderTemplate = void 0;
+exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.TEMPLATE_PACKAGE_BY_STACK = exports.SUPPORTED_STACKS = exports.renderTemplate = void 0;
 var template_1 = require("./template");
 Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return template_1.SUPPORTED_STACKS; } });
@@ -10,3 +10,4 @@ Object.defineProperty(exports, "readSparkMeta", { enumerable: true, get: functio
 Object.defineProperty(exports, "writeSparkMeta", { enumerable: true, get: function () { return spark_meta_1.writeSparkMeta; } });
 var install_1 = require("./install");
 Object.defineProperty(exports, "installDependencies", { enumerable: true, get: function () { return install_1.installDependencies; } });
+Object.defineProperty(exports, "resolveNpmInstallRegistry", { enumerable: true, get: function () { return install_1.resolveNpmInstallRegistry; } });

package/dist/services/deploy/modern/atoms/local-release.js

@@ -10,8 +10,13 @@ const logger_1 = require("../../../../utils/logger");
  * 创建本地发布单（加锁；不挂 pipeline）。
  * 返回的 releaseId 必须由 finalizeLocalRelease 翻为终态，否则发布单一直挂着。
  */
-async function createLocalRelease(appId, version) {
-    return (0, index_1.createLocalRelease)({ appID: appId, version });
+async function createLocalRelease(appId, version, extra) {
+    return (0, index_1.createLocalRelease)({
+        appID: appId,
+        version,
+        checkPointVersion: extra?.checkPointVersion,
+        commitID: extra?.commitID,
+    });
 }
 /**
  * 把本地发布单翻为终态。Finished / Failed 由 pipeline 视上下游结果决定。

package/dist/services/deploy/modern/pipelines/local.js

@@ -43,7 +43,10 @@ async function localBuildLocalPublishPipeline(opts) {
         });
     }
     (0, logger_1.log)('deploy', 'Creating local release...');
-    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version);
+    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
+        checkPointVersion: opts.checkPointVersion,
+        commitID: opts.commitID,
+    });
     try {
         (0, logger_1.log)('deploy', 'Uploading artifacts...');
         await (0, index_1.uploadArtifacts)({ projectDir: ctx.projectDir, appId: ctx.appId, data });

package/dist/utils/codemod-client-toolkit-lite.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Codemod：把 `@lark-apaas/client-toolkit-lite` 的 import 改写到 `@lark-apaas/client-toolkit`。
+ *
+ * 用于 `miaoda app migrate vite-react → nestjs-react-fullstack`：迁移后让两个包共存属于
+ * lib 冗余（两份 react / 两套主题 / 两套 axios），所以扫 user 代码把 lite import 改写到
+ * full，然后用 delete-json-keys 移除 lite dep。
+ *
+ * 实现策略：单行包名替换。
+ *
+ * client-toolkit 自 v1.2.48 起在顶层 single-entry 完整 re-export 了 client-toolkit-lite
+ * 的全部 48 项（components / hooks / utils / integrations / logger / trace / types /
+ * constants），跟 lite 同名同签 —— 所以 codemod 只需把 import 来源包名从 `-lite` 换掉，
+ * specifier 列表完全不动。CSS `@import` 同理（client-toolkit 顶层加了 ./styles.css 别名）。
+ *
+ * 边界：
+ *   - 仅处理形如 `import [type] { A, B as C } from '@lark-apaas/client-toolkit-lite'` 的
+ *     named import；default import / namespace import / 跨多行 specifier 当前不识别，
+ *     但只要 `from '...lite'` 在同一行，包名替换仍有效（regex 抓 from 段）。
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rewriteLiteImports = rewriteLiteImports;
+exports.rewriteCssText = rewriteCssText;
+exports.rewriteText = rewriteText;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const LITE_PKG = '@lark-apaas/client-toolkit-lite';
+const FULL_PKG = '@lark-apaas/client-toolkit';
+/**
+ * 递归扫描 rootDir 下的 .ts/.tsx/.js/.jsx/.css 文件，把 lite import 改写到 full。
+ */
+function rewriteLiteImports(rootDir) {
+    const result = {
+        filesScanned: 0,
+        filesChanged: [],
+        rewrittenSymbols: 0,
+        unmapped: [],
+    };
+    if (!node_fs_1.default.existsSync(rootDir))
+        return result;
+    for (const file of walk(rootDir)) {
+        const isJs = /\.(ts|tsx|js|jsx)$/.test(file);
+        const isCss = file.endsWith('.css');
+        if (!isJs && !isCss)
+            continue;
+        result.filesScanned++;
+        const before = node_fs_1.default.readFileSync(file, 'utf-8');
+        if (!before.includes(LITE_PKG))
+            continue;
+        const rel = node_path_1.default.relative(rootDir, file);
+        const { text, count } = isJs ? rewriteText(before, rel) : rewriteCssText(before, rel);
+        if (count > 0) {
+            node_fs_1.default.writeFileSync(file, text);
+            result.filesChanged.push(rel);
+            result.rewrittenSymbols += count;
+        }
+    }
+    return result;
+}
+/**
+ * css 改写器：单行包名替换。`@import "@lark-apaas/client-toolkit-lite/<path>"` →
+ * `@import "@lark-apaas/client-toolkit/<path>"`。其中 styles.css 在 full 端已加同名别名
+ * 指向 ./lib/index.css。
+ */
+function rewriteCssText(source, _fileLabel) {
+    let count = 0;
+    const re = /(@import\s+['"])@lark-apaas\/client-toolkit-lite(\/[^'"]*)?(['"])/g;
+    const text = source.replace(re, (_match, p1, sub, p3) => {
+        count++;
+        return `${p1}${FULL_PKG}${sub ?? ''}${p3}`;
+    });
+    return { text, count, unmapped: [] };
+}
+/**
+ * JS/TS 文件改写器：把任何 `from '@lark-apaas/client-toolkit-lite'` 改成 full 包名。
+ * specifier 列表完全保留 —— full 顶层 single-entry 已经兼容 lite 全部 48 项 export。
+ *
+ * 同样兼容 dynamic import / require / `export ... from` 等其他形式（只要包名字符串在）。
+ */
+function rewriteText(source, _fileLabel) {
+    let count = 0;
+    // 既匹配 `from 'pkg'` 也匹配 `from "pkg"`，单双引号都管。
+    // 同时覆盖 `import('pkg')` / `require('pkg')` 等其他常见形态。
+    const re = /(['"])@lark-apaas\/client-toolkit-lite(['"])/g;
+    const text = source.replace(re, (_match, p1, p2) => {
+        count++;
+        return `${p1}${FULL_PKG}${p2}`;
+    });
+    return { text, count, unmapped: [] };
+}
+function* walk(dir) {
+    for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+            continue;
+        const full = node_path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            yield* walk(full);
+        }
+        else if (entry.isFile()) {
+            yield full;
+        }
+    }
+}

package/dist/utils/migrate-rule.js

@@ -0,0 +1,319 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyMigrateRules = applyMigrateRules;
+exports.rewriteViteConfigForFullstack = rewriteViteConfigForFullstack;
+exports.rewriteAliasSrcPaths = rewriteAliasSrcPaths;
+const node_fs_1 = __importDefault(require("node:fs"));
+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 logger_1 = require("./logger");
+/**
+ * 顺序执行 MigrateRule[]：
+ *   - move-* / set-stack 是 migrate 专有 rule，本模块直接处理。
+ *   - 其余（directory / file / merge-json / delete-* / add-script / ...）全部委派给
+ *     applySyncRules —— 单条调用，逻辑跟 sync 完全对齐，避免行为漂移。
+ *
+ * 一条 rule 报错不影响后续（applySyncRules 内部已有 try/catch；本模块的 applyMove / applySetStack
+ * 当前不 catch —— 如果 move 失败说明状态已经被破坏，应当直接抛错让 handler 决定回滚或上报）。
+ */
+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));
+            continue;
+        }
+        if (rule.type === 'delete-json-keys') {
+            results.push(applyDeleteJsonKeys(rule, opts));
+            continue;
+        }
+        if (rule.type === 'codemod-client-toolkit-lite') {
+            results.push(applyCodemodLite(rule, opts));
+            continue;
+        }
+        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);
+    }
+    return results;
+}
+function applyMove(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const src = node_path_1.default.join(opts.targetDir, rule.from);
+    const dest = node_path_1.default.join(opts.targetDir, rule.to);
+    const onConflict = rule.onConflict ?? 'merge';
+    if (!node_fs_1.default.existsSync(src)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.from} (source not found, skip)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    if (node_fs_1.default.existsSync(dest)) {
+        if (onConflict === 'skip') {
+            (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (already exists, skip per onConflict=skip)`);
+            return { rule, action: 'skipped', path: rule.to };
+        }
+        if (onConflict === 'overwrite') {
+            node_fs_1.default.rmSync(dest, { recursive: true, force: true });
+            moveAtomic(src, dest);
+            (0, logger_1.log)(logPrefix, `  ✓ ${rule.from} → ${rule.to} (overwritten)`);
+            return { rule, action: 'moved', path: rule.to, detail: rule.from };
+        }
+        // 'merge'：把 src 的内容递归 overlay 到 dest，源 entry 完成后整体清掉
+        mergeOverlay(src, dest);
+        node_fs_1.default.rmSync(src, { recursive: true, force: true });
+        (0, logger_1.log)(logPrefix, `  ✓ ${rule.from} → ${rule.to} (merged)`);
+        return { rule, action: 'moved', path: rule.to, detail: rule.from };
+    }
+    // 目标不存在 —— 直接 rename
+    const destDir = node_path_1.default.dirname(dest);
+    if (destDir !== '.' && !node_fs_1.default.existsSync(destDir)) {
+        node_fs_1.default.mkdirSync(destDir, { recursive: true });
+    }
+    moveAtomic(src, dest);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.from} → ${rule.to}`);
+    return { rule, action: 'moved', path: rule.to, detail: rule.from };
+}
+/**
+ * fs.renameSync 在跨设备 / 跨文件系统时报 EXDEV（Linux/macOS），fallback 到 cp -r + rm。
+ * worktree 内通常同一卷不会触发，但 tmp 目录跟 user app 可能不同卷，留这层兜底。
+ */
+function moveAtomic(src, dest) {
+    try {
+        node_fs_1.default.renameSync(src, dest);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV') {
+            throw err;
+        }
+        node_fs_1.default.cpSync(src, dest, { recursive: true });
+        node_fs_1.default.rmSync(src, { recursive: true, force: true });
+    }
+}
+/**
+ * 把 src 的每个 entry 复制到 dest 同路径下（src 是文件则覆盖 dest 同名文件；src 是目录则
+ * 递归创建 + 复制）。同名冲突一律 src 覆盖 dest。本函数不删 src；调用方负责清理。
+ */
+function mergeOverlay(src, dest) {
+    const stat = node_fs_1.default.statSync(src);
+    if (stat.isFile()) {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(dest), { recursive: true });
+        node_fs_1.default.copyFileSync(src, dest);
+        return;
+    }
+    if (!node_fs_1.default.existsSync(dest)) {
+        node_fs_1.default.mkdirSync(dest, { recursive: true });
+    }
+    for (const entry of node_fs_1.default.readdirSync(src)) {
+        mergeOverlay(node_path_1.default.join(src, entry), node_path_1.default.join(dest, entry));
+    }
+}
+function applySetStack(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    (0, spark_meta_1.writeSparkMeta)(opts.targetDir, { stack: rule.stack });
+    (0, logger_1.log)(logPrefix, `  ✓ .spark/meta.json stack → ${rule.stack}`);
+    return { rule, action: 'patched', path: '.spark/meta.json', detail: rule.stack };
+}
+function applyDeleteJsonKeys(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const dest = node_path_1.default.join(opts.targetDir, rule.to);
+    if (!node_fs_1.default.existsSync(dest)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip delete-json-keys)`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const text = node_fs_1.default.readFileSync(dest, 'utf-8');
+    const json = JSON.parse(text);
+    const deleted = [];
+    for (const dotKey of rule.keys) {
+        if (deleteAtDotPath(json, dotKey))
+            deleted.push(dotKey);
+    }
+    if (deleted.length === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (no listed keys present)`);
+        return { rule, action: 'noop', path: rule.to };
+    }
+    // 保持原文件末尾换行约定（package.json 一般以 \n 结尾）
+    const trailing = text.endsWith('\n') ? '\n' : '';
+    node_fs_1.default.writeFileSync(dest, JSON.stringify(json, null, 2) + trailing);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (deleted ${deleted.length.toString()} key(s): ${deleted.join(', ')})`);
+    return { rule, action: 'patched', path: rule.to, detail: deleted.join(',') };
+}
+function applyCodemodLite(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const root = node_path_1.default.join(opts.targetDir, rule.root ?? 'client/src');
+    const r = (0, codemod_client_toolkit_lite_1.rewriteLiteImports)(root);
+    if (r.filesChanged.length === 0 && r.unmapped.length === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.root ?? 'client/src'} (no @lark-apaas/client-toolkit-lite imports found)`);
+        return { rule, action: 'noop', path: rule.root ?? 'client/src' };
+    }
+    const detail = `${r.rewrittenSymbols.toString()} symbol(s) in ${r.filesChanged.length.toString()} file(s)` +
+        (r.unmapped.length > 0 ? `; ${r.unmapped.length.toString()} unmapped` : '');
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.root ?? 'client/src'} (codemod: ${detail})`);
+    for (const u of r.unmapped) {
+        (0, logger_1.log)(logPrefix, `    ⚠ unmapped: ${u.file}:${u.line.toString()} '${u.symbol}'`);
+    }
+    return {
+        rule,
+        action: r.rewrittenSymbols > 0 ? 'patched' : 'noop',
+        path: rule.root ?? 'client/src',
+        detail,
+    };
+}
+function applyCodemodViteConfigFullstack(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const rel = rule.to ?? 'vite.config.ts';
+    const dest = node_path_1.default.join(opts.targetDir, rel);
+    if (!node_fs_1.default.existsSync(dest)) {
+        (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 { text, aliasRewriteCount } = rewriteViteConfigForFullstack(before);
+    if (aliasRewriteCount === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rel} (no src alias path to rewrite)`);
+        return { rule, action: 'noop', path: 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)`,
+    };
+}
+/**
+ * 把 vite.config.ts 里 alias 字符串里 `src` 起头的路径重写到 `client/src`。
+ *
+ * vite-react 时代 user 业务代码在 `src/`，迁移后搬到 `client/src/`，vite.config
+ * 里的 alias（典型如 `'@': path.resolve(__dirname, 'src')`）必须同步改：
+ *   path.resolve(<args>, 'src')        → 'src' 替换为 'client/src'
+ *   path.resolve(<args>, 'src/<rest>') → 同上
+ *   path.join(<args>, 'src')           → 同上
+ *   './src' / './src/<rest>' 字符串    → './client/src' / './client/src/<rest>'
+ * 边界：仅匹配整段 'src' 起头（避免 'sub/src' 误改），保留单/双引号原样。
+ *
+ * 注：fullstack 形态识别 **不再** 通过 `defineConfig` 的 option 第二参，而是
+ * 由 `coding-preset-vite-react` 内部读 `process.env.MIAODA_APP_TYPE === '3'`
+ * 自动判断（fullstack stack 的 archType 是 3）—— 所以 vite.config 完全不需要
+ * 加 option，只需 alias 路径同步即可。
+ */
+function rewriteViteConfigForFullstack(source) {
+    const { text, count } = rewriteAliasSrcPaths(source);
+    return { text, aliasRewriteCount: count };
+}
+/**
+ * vite.config 里 alias 路径重写：`src` 起头的路径加 `client/` 前缀。
+ *
+ * 匹配的形态（不限制在 resolve.alias 块内 —— vite.config 顶层很少出现非 alias 用的
+ * `src` 字符串，业务 import 走 `@/...`，所以全文匹配是安全的）：
+ *
+ *   path.resolve(<args>, 'src')             → path.resolve(<args>, 'client/src')
+ *   path.resolve(<args>, 'src/<rest>')      → path.resolve(<args>, 'client/src/<rest>')
+ *   path.join(<args>, 'src')                → 同上
+ *   './src' / './src/<rest>'（独立字符串）  → './client/src' / './client/src/<rest>'
+ *
+ * 已含 `client/src` 的不动（视为已迁移），`sub/src` 之类（src 不在词首）不动。
+ */
+function rewriteAliasSrcPaths(source) {
+    let count = 0;
+    // path.resolve(...) / path.join(...) 的最后一个参数是 'src' 或 'src/...' 起头
+    // 匹配 ['"]src[/'"]，保留引号
+    const pathCallRe = /(\bpath\s*\.\s*(?:resolve|join)\s*\([^)]*?,\s*)(['"`])(src)(\/[^'"`]*)?(['"`])/g;
+    let next = source.replace(pathCallRe, (_match, prefix, q1, _src, rest, q2) => {
+        count++;
+        return `${prefix}${q1}client/src${rest ?? ''}${q2}`;
+    });
+    // 独立的相对路径字符串字面量 './src' 或 './src/...'（不在 path.resolve 参数里）
+    // 注意：path.resolve / join 已被上一步处理，这里只匹配剩下的 './src...' 字面量。
+    // 这种用法在 vite.config 较少（典型是直接给 alias 字符串值），但兜底处理。
+    const relativeRe = /(['"`])\.\/(src)(\/[^'"`]*)?(['"`])/g;
+    next = next.replace(relativeRe, (_match, q1, _src, rest, q2) => {
+        count++;
+        return `${q1}./client/src${rest ?? ''}${q2}`;
+    });
+    return { text: next, count };
+}
+function applyAddDepsFromTemplate(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const userPath = node_path_1.default.join(opts.targetDir, rule.to ?? 'package.json');
+    const tplPath = node_path_1.default.join(opts.sourceRoot, rule.from ?? 'package.json');
+    if (!node_fs_1.default.existsSync(userPath)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to ?? 'package.json'} (not found, skip add-deps-from-template)`);
+        return { rule, action: 'skipped', path: rule.to ?? 'package.json' };
+    }
+    if (!node_fs_1.default.existsSync(tplPath)) {
+        (0, logger_1.log)(logPrefix, `  ⚠ template ${rule.from ?? 'package.json'} not found, skip add-deps-from-template`);
+        return { rule, action: 'skipped', path: rule.to ?? 'package.json' };
+    }
+    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 added = [];
+    const missingInTpl = [];
+    for (const grp of ['dependencies', 'devDependencies']) {
+        const whitelist = rule[grp] ?? [];
+        if (whitelist.length === 0)
+            continue;
+        userJson[grp] ??= {};
+        for (const dep of whitelist) {
+            // 在 template 里找版本号：优先 tpl 同 grp，其次另一 grp（template 可能把 dep 写在
+            // dependencies/devDependencies 任一处，跟 user 当前 grp 不一定一致）
+            const tplVersion = tplJson[grp]?.[dep] ??
+                (grp === 'dependencies' ? tplJson.devDependencies?.[dep] : tplJson.dependencies?.[dep]);
+            if (tplVersion === undefined) {
+                missingInTpl.push(dep);
+                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)`);
+        return { rule, action: 'noop', path: rule.to ?? 'package.json' };
+    }
+    const trailing = userText.endsWith('\n') ? '\n' : '';
+    node_fs_1.default.writeFileSync(userPath, JSON.stringify(userJson, null, 2) + trailing);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to ?? 'package.json'} (added ${added.length.toString()} dep(s)${missingInTpl.length > 0 ? `; ${missingInTpl.length.toString()} missing in template: ${missingInTpl.join(', ')}` : ''})`);
+    return {
+        rule,
+        action: 'patched',
+        path: rule.to ?? 'package.json',
+        detail: added.join(','),
+    };
+}
+/**
+ * 按 dot path 删除嵌套对象里的一个 leaf key。返回是否真的删了一项。
+ * 不支持包含 `.` 的字段名（实际 dep 名 / scripts 名不会含 `.`，够用）。
+ */
+function deleteAtDotPath(obj, dotPath) {
+    const parts = dotPath.split('.');
+    let cursor = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const next = cursor[parts[i]];
+        if (next === undefined || next === null || typeof next !== 'object')
+            return false;
+        cursor = next;
+    }
+    const leaf = parts[parts.length - 1];
+    if (!Object.prototype.hasOwnProperty.call(cursor, leaf))
+        return false;
+    // 用 Reflect.deleteProperty 避开 eslint 对 `delete obj[computedKey]` 的禁用规则
+    return Reflect.deleteProperty(cursor, leaf);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.16-beta.70f1b39",
+  "version": "0.1.17-alpha.0",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -17,6 +17,20 @@
     "dist",
     "upgrade"
   ],
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src/ --max-warnings 0",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "vitest run --project=unit",
+    "test:watch": "vitest --project=unit",
+    "test:integration": "vitest run --project=integration",
+    "dev": "node --import tsx src/main.ts",
+    "cli": "node --env-file-if-exists=integration/.env --import tsx src/main.ts",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm format:check && pnpm lint && pnpm build && pnpm test"
+  },
   "keywords": [
     "miaoda",
     "cli",
@@ -51,16 +65,5 @@
     "vitest": "^4.1.4",
     "xml2js": "^0.6.2"
   },
-  "scripts": {
-    "build": "bash scripts/build.sh",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "lint": "eslint src/ --max-warnings 0",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "test": "vitest run --project=unit",
-    "test:watch": "vitest --project=unit",
-    "test:integration": "vitest run --project=integration",
-    "dev": "node --import tsx src/main.ts",
-    "cli": "node --env-file-if-exists=integration/.env --import tsx src/main.ts"
-  }
-}
+  "packageManager": "pnpm@10.16.1+sha512.0e155aa2629db8672b49e8475da6226aa4bdea85fdcdfdc15350874946d4f3c91faaf64cbdc4a5d1ab8002f473d5c3fcedcd197989cf0390f9badd3c04678706"
+}