@lark-apaas/miaoda-cli 0.1.46 → 0.1.47

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

@@ -2,25 +2,32 @@
 /**
  * vite-react → nestjs-react-fullstack 的跨 stack 迁移规则。
  *
- * 设计原则：**最小改动**。只动 fullstack 形态必须的文件 / package.json key，user 已有
- * 的 vite.config / tsconfig / eslint / prettier / tailwind / postcss / components.json
- * 等业务配置一律**保留**，不被 template 整体覆盖。
+ * 设计原则：**明确托管清单 + 定向适配 + 冲突按调用方策略处理**。
+ *   - 明确托管的平台文件（scripts 清单、.githooks/pre-commit）按兼容模板整文件更新；清单外的
+ *     scripts/ 用户文件保留。
+ *   - 业务代码、server/shared、插件不整目录覆盖：只补平台启动所需的缺失文件，已有 app.module.ts
+ *     定向注册平台模块。
+ *   - package.json / tsconfig / vite.config / index.html 等混合配置只改本次运行要求的部分，
+ *     保留 alias、paths、用户编译选项、HTML 自定义 head、额外 scripts 等业务部分。
+ *   - 无法确定性处理（同路径不同内容、同 ID 插件、自定义同名 script、不支持的配置形态）一律
+ *     action=conflict。冲突策略 stop（平台调用）下：执行前对原目录预检可识别冲突（不写盘），执行中
+ *     出现的冲突即停止，不覆盖用户内容；overwrite（手动 / Agent 调用）下按各规则说明用模板替换，
+ *     替换不了的保留用户内容（见 config/migrate.ts 各规则类型）。
  *
  * 步骤：
- *   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/* + SWC 工具链 + 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
+ *   1. src/ public/ 搬到 client/ 下（同名不同内容 → 冲突）
+ *   2. 旧 stack 平台残留：补 eslint.config.js 并带上旧配置的 globalIgnores，eslint.config.mjs 仅在是
+ *      平台默认内容时删除；lockfile 删除（依赖集合变化）
+ *   3. 删 user package.json 里 lite SDK / type=module
+ *   4. server 平台启动文件按缺失补齐 + app.module.ts 定向注册 PlatformModule / ViewModule
+ *   5. nest-cli.json 合并、tsconfig 三件套定向适配（exclude 随布局改写）、stylelint 缺失补齐
+ *   6. 根 index.html → client/index.html（HBS 骨架 + 用户 head/body 自定义部分）
+ *   7. 托管脚本清单更新；shared / .env 缺失补齐
+ *   8. 插件 shared/capabilities → server/capabilities（重复 ID 检查）
+ *   9. scripts 定向适配（旧平台写法改写、自定义同名冲突）
+ *  10. 从 fullstack template/package.json 取版本号，精确加 NestJS 强依赖白名单（SWC 钉 lockfile 版本）
+ *  11. codemod：lite → client-toolkit；vite.config alias src → client/src
+ *  12. set-stack 切 .spark/meta.json
  *
  * 跟 SDK 的协作：client-toolkit@1.2.52+ 顶层 single-entry 完整 re-export 了
  * client-toolkit-lite 全部 48 项 API（fullstack-plugin#1124），所以 codemod 只换
@@ -28,24 +35,76 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIGRATE_CONFIG = void 0;
+const fullstack_cli_pin_1 = require("../../config/fullstack-cli-pin");
+const fullstack_managed_files_1 = require("../../config/fullstack-managed-files");
+/**
+ * vite-react 模板默认的 eslint.config.mjs（规范化后）结构：只引 eslint/config 与
+ * @lark-apaas/coding-presets-react，导出 [globalIgnores([...]), ...eslintPresets.client]。
+ * 命中即视为平台默认、可由 fullstack 的 eslint.config.js 取代；否则视为用户定制 → 冲突。
+ */
+const VITE_REACT_DEFAULT_ESLINT = 'import\\{globalIgnores\\}from"eslint/config"' +
+    'import\\{eslintPresets\\}from"@lark-apaas/coding-presets-react"' +
+    'exportdefault\\[(globalIgnores\\(\\[("[^"]*",?)*\\]\\),?)?\\.\\.\\.eslintPresets\\.client,?\\]';
+/**
+ * 早期 vite-react 模板（coding-template-vite-react 0.1.8～0.1.17，2026-05～06 初）默认的
+ * eslint.config.mjs（规范化后）：自包含的 flat config，直接引 @eslint/js / typescript-eslint /
+ * react-hooks / react-refresh，没有平台 preset。忽略列表允许不同。
+ */
+const VITE_REACT_EARLY_DEFAULT_ESLINT = 'importjsfrom"@eslint\\/js"' +
+    'importglobalsfrom"globals"' +
+    'importreactHooksfrom"eslint-plugin-react-hooks"' +
+    'importreactRefreshfrom"eslint-plugin-react-refresh"' +
+    'importtseslintfrom"typescript-eslint"' +
+    'import\\{defineConfig,globalIgnores\\}from"eslint\\/config"' +
+    'exportdefaultdefineConfig\\(\\[' +
+    'globalIgnores\\(\\[("[^"]*",?)*\\]\\),' +
+    '\\{files:\\["\\*\\*\\/\\*\\.\\{ts,tsx\\}"\\],' +
+    'extends:\\[js\\.configs\\.recommended,tseslint\\.configs\\.recommended,reactHooks\\.configs\\.flat\\.recommended,reactRefresh\\.configs\\.vite,\\],' +
+    'languageOptions:\\{ecmaVersion:2020,globals:globals\\.browser,\\},' +
+    'rules:\\{"react-refresh\\/only-export-components":"off","@typescript-eslint\\/no-unused-vars":"off","@typescript-eslint\\/no-explicit-any":"off","@typescript-eslint\\/no-empty-object-type":"off","@typescript-eslint\\/no-require-imports":"off","no-empty":"off","prefer-const":"off","no-unused-labels":"off",\\},\\},\\]\\)';
 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' },
+        // ===== 1. 用户领地搬迁（同名不同内容冲突，不覆盖） =====
+        { type: 'move-directory', from: 'src', to: 'client/src', onConflict: 'fail' },
+        { type: 'move-directory', from: 'public', to: 'client/public', onConflict: 'fail' },
         // 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' },
+        // ===== 2. 清理 vite-react 平台残留 =====
+        // ESLint 9 flat config 文件名变了（eslint.config.mjs → eslint.config.js）：先补新配置（用户已有则
+        // 保留），把旧配置 globalIgnores 的条目带过去 —— vite-react 模板排除了 **/components/ui/**，
+        // 不带过去 shadcn 组件会被 lint，组件里引用新版 react-hooks 规则的 disable 注释报"规则不存在"。
+        { type: 'file', from: 'eslint.config.js', to: 'eslint.config.js', overwrite: false },
+        { type: 'carry-eslint-ignores', from: 'eslint.config.mjs', to: 'eslint.config.js' },
+        // 新 preset（fullstack-presets simple client）比旧 preset（coding-presets-react）新增 / 加严的 error 级规则，
+        // 旧代码按旧规则合规、迁移后才违规，降为 warn，不让平台规范的增量拦下整次转换
+        {
+            type: 'relax-eslint-rules',
+            to: 'eslint.config.js',
+            files: ['client/**/*.{ts,tsx}', 'shared/**/*.{ts,tsx}'],
+            rules: [
+                '@lark-apaas/require-app-container',
+                '@lark-apaas/no-direct-capability-api',
+                '@lark-apaas/no-multiline-styled-jsx-classname',
+                '@lark-apaas/no-nested-styled-jsx',
+                '@lark-apaas/no-styled-jsx-data-uri-url-ref',
+                'import/no-unresolved',
+                'no-restricted-syntax',
+            ],
+        },
+        // 旧配置用户改过则冲突
+        {
+            type: 'remove-known-default',
+            to: 'eslint.config.mjs',
+            knownDefaults: [VITE_REACT_DEFAULT_ESLINT, VITE_REACT_EARLY_DEFAULT_ESLINT],
+            reason: 'customized ESLint config (eslint.config.mjs) cannot be converted automatically; move custom rules into eslint.config.js extending @lark-apaas/fullstack-presets, then retry',
+        },
+        // 依赖集合变了，lockfile 由原目录里的 npm install 重新生成。
+        // repair（已是目标布局）不删：只补安装，不重解析用户已锁定的依赖树。
+        { type: 'delete-file', to: 'package-lock.json', migrateOnly: true },
         // ===== 3. 从 user package.json 删 vite-react 专属字段 =====
         // 注意保留 devDependencies.@lark-apaas/coding-preset-vite-react —— user 迁移后
-        // vite.config 仍用它（开 fullstack 模式即可），不切到 fullstack-vite-preset。
+        // vite.config 仍用它（由 MIAODA_APP_TYPE 开启全栈模式），不切到 fullstack-vite-preset。
         {
             type: 'delete-json-keys',
             to: 'package.json',
@@ -56,187 +115,142 @@ exports.MIGRATE_CONFIG = {
                 '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：整文件采用当前 fullstack template，除 Nest build 入口外还必须带上
-        // compilerOptions.builder.type=swc 及配套 typeCheck/options。若这里只保留旧的空配置
-        // 或字段级残缺合并，即使 package.json 已补齐 SWC 依赖，Nest 仍会回退到 TSC 构建。
-        { 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 },
-        // stylelint 配置 —— package.json 加了 `stylelint` script（下面 add-script 那条）
-        // + npm run precommit 会调它，缺配置文件时报 `No configuration provided for
-        // client/src/index.css`。fullstack template 的 .stylelintrc.js extends
-        // @lark-apaas/fullstack-presets 的 stylelintPresetsOfSimple。
-        { type: 'file', from: '.stylelintrc.js', to: '.stylelintrc.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 },
-        // ===== 4.5. plugin 实例从 shared/capabilities 搬到 server/capabilities =====
-        // vite-react (jsPage) 时期 plugin 实例 json 放在 shared/capabilities/<id>.json，
-        // fullstack 形态走 server 侧装载,路径约定改成 server/capabilities/<id>.json。
-        // 顺序约束:必须在 server/ 覆盖之后 —— server/ 是 overwrite:true,放前面会被擦掉。
-        { type: 'move-directory', from: 'shared/capabilities', to: 'server/capabilities' },
-        // ===== 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,
-        },
+        // ===== 4. server：只补平台启动所需的缺失文件，不覆盖业务 server =====
+        { type: 'file', from: 'server/main.ts', to: 'server/main.ts', overwrite: false },
+        { type: 'file', from: 'server/app.module.ts', to: 'server/app.module.ts', overwrite: false },
+        { type: 'directory', from: 'server/common', to: 'server/common', overwrite: false },
+        { type: 'directory', from: 'server/modules/view', to: 'server/modules/view', overwrite: false },
+        // 已有业务 app.module.ts：定向注册 PlatformModule / ViewModule；main.ts 必须走平台 bootstrap
+        { type: 'adapt-nest-app-module', to: 'server/app.module.ts', checkMain: 'server/main.ts' },
+        // ===== 5. 构建 / 类型 / lint 配置 =====
+        // nest-cli.json：缺失时取模板；已存在时字段级合并（builder.type=swc 等平台键取模板值，
+        // 用户 assets / plugins 按 key 保留）。漏掉 SWC builder 会让 Nest 回退 TSC 构建。
         {
-            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,
+            type: 'merge-json',
+            from: 'nest-cli.json',
+            to: 'nest-cli.json',
+            arrayMerge: {
+                'compilerOptions.assets': { key: 'include' },
+                'compilerOptions.plugins': { key: 'name' },
+            },
         },
-        // ----- 平台脚本调用链 -----
-        // 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 不会自定义,直接覆盖。
+        // tsconfig：定向适配 —— 保留用户 paths / 编译选项，只改布局（src → client/src）与平台 preset
+        { type: 'adapt-tsconfig', role: 'root', from: 'tsconfig.json', to: 'tsconfig.json' },
         {
-            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: 'adapt-tsconfig',
+            role: 'app',
+            from: 'tsconfig.app.json',
+            to: 'tsconfig.app.json',
+            legacyExtends: [
+                '@lark-apaas/coding-presets-react/lib/tsconfig/tsconfig.app.json',
+                // 早期模板（0.1.8～0.1.17）的 preset 包名
+                '@lark-apaas/coding-presets/lib/tsconfig/tsconfig.app.json',
+            ],
         },
+        { type: 'adapt-tsconfig', role: 'node', from: 'tsconfig.node.json', to: 'tsconfig.node.json' },
+        // stylelint：缺失时补模板（用户已有则保留）；eslint.config.js 已在第 2 步补齐
+        // package.json 的 `stylelint` script + precommit 会调它，缺配置时报 `No configuration provided`
+        { type: 'file', from: '.stylelintrc.js', to: '.stylelintrc.js', overwrite: false },
+        // ===== 6. HTML 入口：根 index.html → client/index.html（HBS） =====
         {
-            type: 'add-script',
-            name: 'precommit',
-            command: 'node scripts/hooks/run-precommit.js',
-            overwrite: true,
+            type: 'adapt-html-entry',
+            from: 'index.html',
+            to: 'client/index.html',
+            template: 'client/index.html',
+            legacyEntry: '/src/index.tsx',
         },
+        // ===== 7. 平台托管文件（明确清单）；shared / .env 缺失补齐 =====
+        // dev.sh exec node dev.js，dev.js 才是并发起 nest + vite 的核心 —— 漏一个 dev 跑不起来。
+        // 只更新清单内文件；vite-react 时代的 scripts/dev.mjs 等清单外文件原样保留。
+        ...(0, fullstack_managed_files_1.managedFileRules)(),
+        { type: 'directory', from: 'shared', to: 'shared', overwrite: false },
+        { type: 'file', from: '.env', to: '.env', overwrite: false },
+        // ===== 8. 插件实例 shared/capabilities → server/capabilities（重复 ID 检查） =====
+        // vite-react (jsPage) 时期 plugin 实例 json 放在 shared/capabilities/<id>.json，
+        // fullstack 形态走 server 侧装载，路径约定改成 server/capabilities/<id>.json。
+        { type: 'move-capabilities', from: 'shared/capabilities', to: 'server/capabilities' },
+        // ===== 9. scripts 定向适配 =====
+        // 平台脚本调用链需要的 script：缺失补齐；命中已识别旧平台写法改写；用户自定义同名 → 冲突。
+        //   build.sh 跑 `npm run gen:openapi` / build:client / build:server；
+        //   scripts/lint.js spawn `npm run eslint` / `npm run stylelint`。
         {
-            type: 'add-script',
-            name: 'upgrade',
-            command: 'npx -y @lark-apaas/fullstack-cli sync --disable-gen-openapi',
-            overwrite: true,
+            type: 'ensure-scripts',
+            to: 'package.json',
+            scripts: [
+                {
+                    name: 'dev',
+                    command: './scripts/dev.sh',
+                    legacy: ['node scripts/dev.mjs'],
+                    legacyPrefixes: ['npm run upgrade && '],
+                },
+                { name: 'dev:server', command: 'NODE_ENV=development nest start --watch' },
+                { name: 'dev:client', command: 'NODE_ENV=development vite --config vite.config.ts' },
+                { name: 'build', command: './scripts/build.sh', legacy: ['bash scripts/build.sh'] },
+                { name: 'build:server', command: 'NODE_ENV=production nest build' },
+                {
+                    name: 'build:client',
+                    command: 'NODE_ENV=production vite build --config vite.config.ts',
+                    legacy: ['NODE_ENV=production vite build'],
+                },
+                { name: 'build:prod', command: 'npm run build:server && npm run build:client' },
+                { name: 'start', command: 'NODE_ENV=production node main.js' },
+                { name: 'type:check:server', command: 'tsc --noEmit --project tsconfig.node.json' },
+                { name: 'type:check:client', command: 'tsc --noEmit --project tsconfig.app.json' },
+                {
+                    name: 'type:check',
+                    command: 'concurrently -n "server,client" -c "blue,green" "npm run type:check:server" "npm run type:check:client"',
+                },
+                { name: 'gen:openapi', command: "echo 'UNSUPPORTED, SKIP'" },
+                {
+                    name: 'gen:db-schema',
+                    command: 'npx -y @lark-apaas/db-schema-sync@latest --output server/database/schema.ts --export-custom-types',
+                    legacyPrefixes: [
+                        'fullstack-cli gen-db-schema',
+                        `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} gen-db-schema`,
+                    ],
+                },
+                { name: 'eslint', command: 'eslint . --quiet' },
+                { name: 'stylelint', command: 'stylelint client/src/**/*.css --quiet' },
+                {
+                    name: 'lint',
+                    command: 'node ./scripts/lint.js',
+                    legacy: ['concurrently npm:typecheck npm:lint:eslint'],
+                    legacyPrefixes: ['concurrently '],
+                },
+                {
+                    name: 'precommit',
+                    command: 'node scripts/hooks/run-precommit.js',
+                    legacy: ['npm run lint'],
+                },
+                {
+                    name: 'prepare',
+                    command: 'chmod +x .githooks/pre-commit 2>/dev/null; git config core.hooksPath .githooks 2>/dev/null || true',
+                    legacy: ['node scripts/setup-git-hooks.mjs'],
+                    keepCustom: true,
+                },
+                {
+                    name: 'upgrade',
+                    command: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
+                    legacyPrefixes: ['fullstack-cli sync', 'npx -y @lark-apaas/fullstack-cli sync'],
+                },
+            ],
         },
-        // ----- user 可能自定义的 scripts -----
-        // format/test 多半 user 自己改过(prettier 配 / jest 配),保留 user 自有值。
+        // user 可能自定义的 scripts：只在缺失时补，不改用户已有值
         {
             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', 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 强依赖（精确白名单） =====
+        // ===== 10. 从 fullstack template 取版本号加 NestJS 强依赖（精确白名单） =====
         // 不走 merge-json（template 130+ devDeps 全 merge 会污染 user 业务依赖集合）；
         // 白名单只列 fullstack 启动能跑起来必需的最小集。
         {
@@ -275,7 +289,7 @@ exports.MIGRATE_CONFIG = {
                 // nest start / nest build 必需
                 '@nestjs/cli',
                 '@nestjs/testing',
-                // nest-cli.json 会被上面的 file rule 覆盖成 builder.type=swc。Nest CLI 只负责
+                // nest-cli.json 会被上面的 merge-json 合并成 builder.type=swc。Nest CLI 只负责
                 // 调度 builder，不会自带 SWC 可执行入口和 native compiler；两者必须一起从
                 // 当前目标模板取版本写入迁移后 package.json。若漏掉，前端应用升级成全栈后
                 // 配置已经选择 SWC，但全新的依赖安装树里找不到 @swc/cli/@swc/core，冷启动和
@@ -299,18 +313,32 @@ exports.MIGRATE_CONFIG = {
                 // 配套的 .stylelintrc.js 由上面 file rule 从 template 搬过来。
                 'stylelint',
             ],
+            // SWC 钉模板 lockfile 里的精确版本：迁移删了用户 lockfile，^range 会解析到模板发布之后的
+            // 新版本（@swc/core 1.16.18 在沙箱里加载 native binding 失败，nest 起不来）。钉 lockfile
+            // 版本后与同版本模板新建的应用一致，模板升级 SWC 时自动跟随。
+            exactFromLock: ['@swc/cli', '@swc/core'],
         },
-        // ===== 7. 业务代码 codemod：lite → client-toolkit 包名替换 =====
+        // 10b. 托管构建脚本的配套依赖（@vercel/nft，build.sh → prune-smart.js）：缺失才补固定版本，
+        //      已声明保持用户版本。迁移 / repair 的验证要跑完整 npm run build。
+        ...(0, fullstack_managed_files_1.managedBuildDependencyRules)(),
+        // ===== 11. 业务代码 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 =====
+        // ===== 11b. vite.config：alias 路径 src → client/src =====
+        // 全栈模式由 coding-preset-vite-react 读 MIAODA_APP_TYPE 开启 dev-proxy（vite 8080 反代 HTML /
+        // API 到 nest 3000）；用户 vite.config 不用该 preset 时无法确定性适配 → 冲突。缺失时补模板。
+        {
+            type: 'codemod-vite-config-fullstack',
+            to: 'vite.config.ts',
+            template: 'vite.config.ts',
+            requirePreset: '@lark-apaas/coding-preset-vite-react',
+            // 早期模板（0.1.8～0.1.10）的 preset 包名：配置里只有 defineConfig({ resolve.alias })，换包等价；
+            // 新包在 followLatestPackages 里，安装时补上
+            legacyPresets: ['@lark-apaas/coding-vite-preset'],
+        },
+        // ===== 12. 切 stack =====
         { type: 'set-stack', stack: 'nestjs-react-fullstack' },
     ],
     // install 收尾要钉 latest 的关键平台包 —— 见 MigrateConfig.followLatestPackages 注释。
@@ -318,5 +346,7 @@ exports.MIGRATE_CONFIG = {
     //     这些 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'],
+    // 不配置 verify（不做完整构建）：发布时 DevOps 构建机会完整构建一次，转换问题在预览 / 发布时暴露；
+    // 沙箱里跑模板 build.sh 还会经裸名 `npx fullstack-cli` 解析到公网同名第三方包。
 };
 exports.default = exports.MIGRATE_CONFIG;

package/dist/config/sync-configs/design-stack.js

@@ -58,19 +58,18 @@ exports.SYNC_CONFIG = {
             to: '.gitignore',
             line: '.npm_cache',
         },
-        // 3. 老 npm scripts 迁移（裸 fullstack-cli → 钉版 npx）。两条 ifStartsWith 分别覆盖
-        //    "裸 fullstack-cli"（最老形态）和 "npx 未钉版" 形态，统一升到 FULLSTACK_CLI_PIN_SPEC。
+        // 3. 完整旧平台 postinstall 迁移到 scoped npx，保留用户追加命令和自定义参数。
         {
             type: 'patch-script',
             name: 'postinstall',
             to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
-            ifStartsWith: 'fullstack-cli action-plugin init',
+            ifMatches: [/^fullstack-cli action-plugin init$/],
         },
         {
             type: 'patch-script',
             name: 'postinstall',
             to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
-            ifStartsWith: 'npx -y @lark-apaas/fullstack-cli action-plugin init',
+            ifMatches: [/^npx -y @lark-apaas\/fullstack-cli action-plugin init$/],
         },
         {
             type: 'patch-script',

package/dist/config/sync-configs/nestjs-react-fullstack.js

@@ -10,24 +10,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYNC_CONFIG = void 0;
 const fullstack_cli_pin_1 = require("../../config/fullstack-cli-pin");
+const fullstack_managed_files_1 = require("../../config/fullstack-managed-files");
 exports.SYNC_CONFIG = {
     sync: [
         // ===== fullstack-cli sync 同款规则（对齐沙箱行为） =====
-        // 1. 派生 scripts 目录（包含 dev.sh / dev-local.js / dev.js / build.sh / run.sh /
-        //    lint.js / prune-smart.js / hooks/run-precommit.js；directory rule 自动给 .sh +x）
-        {
-            type: 'directory',
-            from: 'scripts',
-            to: 'scripts',
-            overwrite: true,
-        },
-        // 1a. 同步 .githooks 目录（hook 入口，可执行 sh 脚本）
-        {
-            type: 'directory',
-            from: '.githooks',
-            to: '.githooks',
-            overwrite: true,
-        },
+        // 1. 平台托管文件（明确清单，见 config/fullstack-managed-files.ts）：dev.sh / dev.js /
+        //    dev-local.js / build.sh / run.sh / lint.js / prune-smart.js / hooks/run-precommit.js
+        //    与 .githooks/pre-commit。逐文件同名更新（.sh 自动 +x），清单外的 scripts/ 用户文件保留。
+        ...(0, fullstack_managed_files_1.managedFileRules)(),
         // 1b. scripts.prepare：npm install 后自动激活 git hooks（原生 git，无第三方依赖）
         //     直接写 core.hooksPath，并保底给 pre-commit 加执行位；非 git 仓库下静默退出
         {
@@ -67,28 +57,26 @@ exports.SYNC_CONFIG = {
         // 5. 注册 postinstall 脚本，自动恢复 action plugins。
         //    用 npx -y 形式而不是裸 fullstack-cli：用户项目的 deps 没有 fullstack-cli，
         //    bare 形式在新机器（PATH 没全局 fullstack-cli）下 npm i 立即 ENOENT。
-        //    fullstack-cli 版本临时钉到 FULLSTACK_CLI_PIN_SPEC，避免 npx 走 latest 碰外部回归版本。
         {
             type: 'add-script',
             name: 'postinstall',
             command: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
             overwrite: false,
         },
-        // 5a. 迁移已有应用的老形式 postinstall（裸 fullstack-cli → npx -y 钉版）。
-        //     patch-script 只在脚本以指定前缀开头时改写，用户真正手改过的脚本保持原样。
+        // 5a. 迁移完整旧平台 postinstall（裸 fullstack-cli → scoped npx）。
+        //     整值匹配，保留用户追加命令和自定义参数。
         {
             type: 'patch-script',
             name: 'postinstall',
             to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
-            ifStartsWith: 'fullstack-cli action-plugin init',
+            ifMatches: [/^fullstack-cli action-plugin init$/],
         },
-        // 5b. 迁移已有应用 npx 未钉版的 postinstall —— sync 之前的版本生成的是
-        //     `npx -y @lark-apaas/fullstack-cli action-plugin init`（无版本号），现在统一钉版。
+        // 5b. 迁移完整旧 scoped npx postinstall，显式采用配置的渠道 spec（当前为 latest）。
         {
             type: 'patch-script',
             name: 'postinstall',
             to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
-            ifStartsWith: 'npx -y @lark-apaas/fullstack-cli action-plugin init',
+            ifMatches: [/^npx -y @lark-apaas\/fullstack-cli action-plugin init$/],
         },
         // 5c. gen:db-schema —— 把裸 `fullstack-cli gen-db-schema` 迁到钉版 npx。
         //     这条只在 user app 自己 package.json 已经有 gen:db-schema 时才动（patch-script
@@ -144,7 +132,7 @@ exports.SYNC_CONFIG = {
             to: './scripts/dev.sh',
             ifStartsWith: 'npm run upgrade && ',
         },
-        // 11. 把 `upgrade` 脚本里裸 `fullstack-cli sync` 改成钉版 npx。
+        // 11. 把 `upgrade` 脚本里裸 `fullstack-cli sync` 改成 scoped npx。
         //     跟 postinstall 同款根因：fullstack-cli 不是用户应用的 dep，新机器无全局命令会 ENOENT。
         {
             type: 'patch-script',