@lark-apaas/miaoda-cli 0.1.6 → 0.1.7-alpha.785a451

package/dist/utils/merge-json.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Deep merge JSON 对象，支持按 key 去重合并数组。
+ *
+ * 搬自 @lark-apaas/fullstack-cli/src/utils/merge-json.ts，行为完全对齐：
+ *   - scalar（string / number / boolean / null）：template 覆盖
+ *   - object：递归 merge（template 字段覆盖，user 多出的字段保留）
+ *   - 在 arrayMerge 配置里的 array：按指定 key 去重合并（template item 覆盖同 key 的 user item，
+ *     user 多出的 item 保留）
+ *   - 不在 arrayMerge 配置里的 array：template 覆盖
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepMergeJson = deepMergeJson;
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function mergeArrayByKey(userArr, templateArr, key) {
+    const result = [...userArr];
+    for (const templateItem of templateArr) {
+        if (!isPlainObject(templateItem))
+            continue;
+        const templateKey = templateItem[key];
+        const existingIndex = result.findIndex((item) => isPlainObject(item) && item[key] === templateKey);
+        if (existingIndex >= 0) {
+            result[existingIndex] = templateItem;
+        }
+        else {
+            result.push(templateItem);
+        }
+    }
+    return result;
+}
+function deepMergeJson(user, template, arrayMerge = {}, currentPath = '') {
+    const result = { ...user };
+    for (const key of Object.keys(template)) {
+        const fullPath = currentPath ? `${currentPath}.${key}` : key;
+        const templateValue = template[key];
+        const userValue = user[key];
+        if (Array.isArray(templateValue)) {
+            const cfg = Object.prototype.hasOwnProperty.call(arrayMerge, fullPath)
+                ? arrayMerge[fullPath]
+                : undefined;
+            if (cfg !== undefined && Array.isArray(userValue)) {
+                result[key] = mergeArrayByKey(userValue, templateValue, cfg.key);
+            }
+            else {
+                result[key] = templateValue;
+            }
+        }
+        else if (isPlainObject(templateValue)) {
+            if (isPlainObject(userValue)) {
+                result[key] = deepMergeJson(userValue, templateValue, arrayMerge, fullPath);
+            }
+            else {
+                result[key] = templateValue;
+            }
+        }
+        else {
+            result[key] = templateValue;
+        }
+    }
+    return result;
+}

package/dist/utils/platform-sync.js

@@ -0,0 +1,160 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncPlatformControlled = syncPlatformControlled;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const jsonc = __importStar(require("jsonc-parser"));
+const logger_1 = require("../utils/logger");
+function syncPlatformControlled(opts) {
+    const logPrefix = opts.logPrefix ?? 'app-sync';
+    const cliRoot = opts.cliRoot ?? resolveCliRoot();
+    const stackDir = node_path_1.default.join(cliRoot, 'upgrade', 'templates', opts.stack);
+    if (!node_fs_1.default.existsSync(stackDir)) {
+        return { stackFound: false, syncedFiles: [], mergedJsonFiles: [] };
+    }
+    (0, logger_1.log)(logPrefix, `Syncing upgrade/templates/${opts.stack}/ → ${opts.targetDir}`);
+    const syncedFiles = syncFilesDir(node_path_1.default.join(stackDir, 'files'), opts.targetDir, logPrefix);
+    const mergedJsonFiles = applyJsonPatches(node_path_1.default.join(stackDir, 'patches'), opts.targetDir, logPrefix);
+    return {
+        stackFound: true,
+        syncedFiles,
+        mergedJsonFiles,
+    };
+}
+/** 推断 cli 安装根:dist/utils/platform-sync.js 上溯两级即仓根 */
+function resolveCliRoot() {
+    return node_path_1.default.resolve(__dirname, '..', '..');
+}
+/** 递归同步 srcDir 下所有文件到 destDir,保持相对路径;.sh 文件 +x。返回 dest 相对路径列表 */
+function syncFilesDir(srcDir, destDir, logPrefix) {
+    if (!node_fs_1.default.existsSync(srcDir))
+        return [];
+    const synced = [];
+    walk(srcDir, srcDir, destDir, (rel, srcPath, destPath) => {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(destPath), { recursive: true });
+        node_fs_1.default.copyFileSync(srcPath, destPath);
+        if (rel.endsWith('.sh')) {
+            node_fs_1.default.chmodSync(destPath, 0o755);
+        }
+        synced.push(rel);
+        (0, logger_1.log)(logPrefix, `  + ${rel}`);
+    });
+    return synced;
+}
+/** 递归遍历 patchesDir 下每个 JSON 文件,deep merge 到 destDir 对应路径 */
+function applyJsonPatches(patchesDir, destDir, logPrefix) {
+    if (!node_fs_1.default.existsSync(patchesDir))
+        return [];
+    const merged = [];
+    walk(patchesDir, patchesDir, destDir, (rel, patchPath, destPath) => {
+        if (!rel.endsWith('.json')) {
+            (0, logger_1.log)(logPrefix, `  (skip non-json patch: ${rel})`);
+            return;
+        }
+        if (!node_fs_1.default.existsSync(destPath)) {
+            throw new Error(`[${logPrefix}] target JSON not found: ${destPath} ` +
+                `(patches/${rel} 要求项目根含同路径文件;app init 应该先创建它)`);
+        }
+        const patch = readJson(patchPath);
+        const target = readJson(destPath);
+        if (!isPlainObject(patch) || !isPlainObject(target)) {
+            throw new Error(`[${logPrefix}] patch 与 target 必须都是 JSON object: ${rel}`);
+        }
+        const changed = [];
+        for (const key of Object.keys(patch)) {
+            const before = JSON.stringify(target[key]);
+            target[key] = deepMerge(target[key], patch[key]);
+            const after = JSON.stringify(target[key]);
+            if (before !== after)
+                changed.push(key);
+        }
+        if (changed.length > 0) {
+            node_fs_1.default.writeFileSync(destPath, JSON.stringify(target, null, 2) + '\n', 'utf-8');
+            merged.push({ path: rel, keys: changed });
+            (0, logger_1.log)(logPrefix, `  ~ ${rel} (keys: ${changed.join(', ')})`);
+        }
+        else {
+            (0, logger_1.log)(logPrefix, `  = ${rel} (unchanged)`);
+        }
+    });
+    return merged;
+}
+/** 通用递归遍历:对 rootSrc 下每个文件调 visit(rel, srcAbsPath, destAbsPath) */
+function walk(rootSrc, curSrc, destDir, visit) {
+    for (const name of node_fs_1.default.readdirSync(curSrc)) {
+        const srcPath = node_path_1.default.join(curSrc, name);
+        const stat = node_fs_1.default.statSync(srcPath);
+        if (stat.isDirectory()) {
+            walk(rootSrc, srcPath, destDir, visit);
+            continue;
+        }
+        const rel = node_path_1.default.relative(rootSrc, srcPath);
+        const destPath = node_path_1.default.join(destDir, rel);
+        visit(rel, srcPath, destPath);
+    }
+}
+function readJson(filePath) {
+    // 用 jsonc 解析以兼容 tsconfig*/nest-cli.json 等允许注释和 trailing comma 的配置；
+    // 我们仓自带的 patches/*.json 是严格 JSON，jsonc 也读得通。
+    // 写回时仍走 JSON.stringify，注释和 trailing comma 会丢——user app 的 tsconfig 经过
+    // 一次 deep merge 后会变成严格 JSON，可接受（tsc 同样读得动）。
+    const text = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    const errors = [];
+    const parsed = jsonc.parse(text, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+        const first = errors[0];
+        const code = jsonc.printParseErrorCode(first.error);
+        throw new Error(`${filePath}: jsonc parse error ${code} at offset ${String(first.offset)}`);
+    }
+    return parsed;
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** value 是 object 时递归 merge,其它(包括数组)直接以 patch 覆盖 */
+function deepMerge(target, patch) {
+    if (isPlainObject(patch) && isPlainObject(target)) {
+        const merged = { ...target };
+        for (const k of Object.keys(patch)) {
+            merged[k] = deepMerge(target[k], patch[k]);
+        }
+        return merged;
+    }
+    return patch;
+}

package/dist/utils/sync-rule.js

@@ -0,0 +1,295 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySyncRules = applySyncRules;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const jsonc = __importStar(require("jsonc-parser"));
+const file_ops_1 = require("./file-ops");
+const merge_json_1 = require("./merge-json");
+const logger_1 = require("./logger");
+/**
+ * 顺序执行 SyncRule[]，逐条 apply。一条 rule 报错不影响后续 rule（catch + 记录），最终
+ * 在 handler 层决定是否整体 fail。
+ */
+function applySyncRules(rules, opts) {
+    const results = [];
+    for (const rule of rules) {
+        results.push(applyOne(rule, opts));
+    }
+    return results;
+}
+function applyOne(rule, opts) {
+    const { sourceRoot, targetDir } = opts;
+    const logPrefix = opts.logPrefix ?? 'sync';
+    switch (rule.type) {
+        case 'delete-file': {
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            if (!node_fs_1.default.existsSync(dest)) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip delete)`);
+                return { rule, action: 'noop', path: rule.to };
+            }
+            node_fs_1.default.unlinkSync(dest);
+            (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (deleted)`);
+            return { rule, action: 'deleted', path: rule.to };
+        }
+        case 'delete-directory': {
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            if (!node_fs_1.default.existsSync(dest)) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip delete)`);
+                return { rule, action: 'noop', path: rule.to };
+            }
+            node_fs_1.default.rmSync(dest, { recursive: true });
+            (0, logger_1.log)(logPrefix, `  ✗ ${rule.to} (deleted)`);
+            return { rule, action: 'deleted', path: rule.to };
+        }
+        case 'remove-line': {
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            const changed = (0, file_ops_1.removeLineFromFile)(dest, rule.pattern, logPrefix);
+            return { rule, action: changed ? 'patched' : 'noop', path: rule.to };
+        }
+        case 'add-line': {
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            if (!node_fs_1.default.existsSync(dest)) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (not found, skip add-line)`);
+                return { rule, action: 'skipped', path: rule.to };
+            }
+            const content = node_fs_1.default.readFileSync(dest, 'utf-8');
+            const lines = content.split('\n').map((l) => l.trim());
+            if (lines.includes(rule.line)) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (line already present: ${rule.line})`);
+                return { rule, action: 'noop', path: rule.to };
+            }
+            const sep = content.endsWith('\n') ? '' : '\n';
+            node_fs_1.default.appendFileSync(dest, `${sep}${rule.line}\n`);
+            (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (added: ${rule.line})`);
+            return { rule, action: 'patched', path: rule.to };
+        }
+        case 'add-script': {
+            return applyAddScript(rule, targetDir, logPrefix);
+        }
+        case 'patch-script': {
+            return applyPatchScript(rule, targetDir, logPrefix);
+        }
+        case 'merge-json': {
+            return applyMergeJson(rule, sourceRoot, targetDir, logPrefix);
+        }
+        case 'directory': {
+            const src = node_path_1.default.join(sourceRoot, rule.from);
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            if (!node_fs_1.default.existsSync(src)) {
+                (0, logger_1.log)(logPrefix, `  ⚠ source not found: ${rule.from}`);
+                return { rule, action: 'skipped', path: rule.to };
+            }
+            const count = syncDirectory(src, dest, rule.overwrite ?? true);
+            if (count === 0) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to}/ (no new files)`);
+                return { rule, action: 'noop', path: rule.to };
+            }
+            (0, logger_1.log)(logPrefix, `  ✓ ${rule.to}/ (synced ${count.toString()} file(s))`);
+            return { rule, action: 'synced', path: rule.to, detail: `${count.toString()} file(s)` };
+        }
+        case 'file': {
+            const src = node_path_1.default.join(sourceRoot, rule.from);
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            if (!node_fs_1.default.existsSync(src)) {
+                (0, logger_1.log)(logPrefix, `  ⚠ source not found: ${rule.from}`);
+                return { rule, action: 'skipped', path: rule.to };
+            }
+            const onlyIfExists = rule.onlyIfExists ?? false;
+            const overwrite = rule.overwrite ?? true;
+            if (onlyIfExists && !node_fs_1.default.existsSync(dest)) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (skipped, target not exists)`);
+                return { rule, action: 'skipped', path: rule.to };
+            }
+            if (node_fs_1.default.existsSync(dest) && !overwrite) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (skipped, already exists)`);
+                return { rule, action: 'skipped', path: rule.to };
+            }
+            const destDir = node_path_1.default.dirname(dest);
+            if (!node_fs_1.default.existsSync(destDir)) {
+                node_fs_1.default.mkdirSync(destDir, { recursive: true });
+            }
+            node_fs_1.default.copyFileSync(src, dest);
+            (0, logger_1.log)(logPrefix, `  ✓ ${rule.to}`);
+            return { rule, action: 'synced', path: rule.to };
+        }
+        case 'append': {
+            const src = node_path_1.default.join(sourceRoot, rule.from);
+            const dest = node_path_1.default.join(targetDir, rule.to);
+            if (!node_fs_1.default.existsSync(src)) {
+                (0, logger_1.log)(logPrefix, `  ⚠ source not found: ${rule.from}`);
+                return { rule, action: 'skipped', path: rule.to };
+            }
+            const content = node_fs_1.default.readFileSync(src, 'utf-8');
+            const existing = node_fs_1.default.existsSync(dest) ? node_fs_1.default.readFileSync(dest, 'utf-8') : '';
+            if (existing.includes(content.trim())) {
+                (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (already contains content)`);
+                return { rule, action: 'noop', path: rule.to };
+            }
+            node_fs_1.default.appendFileSync(dest, content);
+            (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (appended)`);
+            return { rule, action: 'appended', path: rule.to };
+        }
+    }
+}
+function readPkgJson(pkgPath) {
+    if (!node_fs_1.default.existsSync(pkgPath))
+        return null;
+    return JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
+}
+function writePkgJson(pkgPath, pkg) {
+    node_fs_1.default.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+function applyAddScript(rule, targetDir, logPrefix) {
+    const pkgPath = node_path_1.default.join(targetDir, 'package.json');
+    const pkg = readPkgJson(pkgPath);
+    if (!pkg) {
+        (0, logger_1.log)(logPrefix, `  ⚠ package.json not found, skip add-script ${rule.name}`);
+        return { rule, action: 'skipped', path: 'package.json' };
+    }
+    pkg.scripts ??= {};
+    const overwrite = rule.overwrite ?? false;
+    const has = Object.prototype.hasOwnProperty.call(pkg.scripts, rule.name);
+    if (has && !overwrite) {
+        (0, logger_1.log)(logPrefix, `  ○ scripts.${rule.name} (already exists)`);
+        return { rule, action: 'skipped', path: 'package.json' };
+    }
+    if (pkg.scripts[rule.name] === rule.command) {
+        (0, logger_1.log)(logPrefix, `  ○ scripts.${rule.name} (already set)`);
+        return { rule, action: 'noop', path: 'package.json' };
+    }
+    pkg.scripts[rule.name] = rule.command;
+    writePkgJson(pkgPath, pkg);
+    (0, logger_1.log)(logPrefix, `  ✓ scripts.${rule.name}`);
+    return { rule, action: 'created', path: 'package.json', detail: rule.name };
+}
+function applyPatchScript(rule, targetDir, logPrefix) {
+    const pkgPath = node_path_1.default.join(targetDir, 'package.json');
+    const pkg = readPkgJson(pkgPath);
+    if (!pkg) {
+        (0, logger_1.log)(logPrefix, `  ⚠ package.json not found, skip patch-script ${rule.name}`);
+        return { rule, action: 'skipped', path: 'package.json' };
+    }
+    const current = pkg.scripts?.[rule.name];
+    if (current === undefined) {
+        (0, logger_1.log)(logPrefix, `  ○ scripts.${rule.name} (not present, skip patch)`);
+        return { rule, action: 'skipped', path: 'package.json' };
+    }
+    if (current === rule.to) {
+        (0, logger_1.log)(logPrefix, `  ○ scripts.${rule.name} (already patched)`);
+        return { rule, action: 'noop', path: 'package.json' };
+    }
+    if (!current.startsWith(rule.ifStartsWith)) {
+        (0, logger_1.log)(logPrefix, `  ⚠ scripts.${rule.name} customized, skip patch`);
+        return { rule, action: 'skipped', path: 'package.json' };
+    }
+    pkg.scripts ??= {};
+    pkg.scripts[rule.name] = rule.to;
+    writePkgJson(pkgPath, pkg);
+    (0, logger_1.log)(logPrefix, `  ✓ scripts.${rule.name} (patched)`);
+    return { rule, action: 'patched', path: 'package.json', detail: rule.name };
+}
+function applyMergeJson(rule, sourceRoot, targetDir, logPrefix) {
+    const src = node_path_1.default.join(sourceRoot, rule.from);
+    const dest = node_path_1.default.join(targetDir, rule.to);
+    if (!node_fs_1.default.existsSync(src)) {
+        (0, logger_1.log)(logPrefix, `  ⚠ source not found: ${rule.from}`);
+        return { rule, action: 'skipped', path: rule.to };
+    }
+    const templateContent = JSON.parse(node_fs_1.default.readFileSync(src, 'utf-8'));
+    if (!node_fs_1.default.existsSync(dest)) {
+        const destDir = node_path_1.default.dirname(dest);
+        if (!node_fs_1.default.existsSync(destDir))
+            node_fs_1.default.mkdirSync(destDir, { recursive: true });
+        node_fs_1.default.writeFileSync(dest, `${JSON.stringify(templateContent, null, 2)}\n`);
+        (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (created from template)`);
+        return { rule, action: 'created', path: rule.to };
+    }
+    // 用户项目里的 JSON 可能是 jsonc（tsconfig*、nest-cli.json 都允许 trailing comma / 注释）。
+    // 这里读取走 jsonc-parser，写回继续标准 JSON.stringify。
+    const userRaw = node_fs_1.default.readFileSync(dest, 'utf-8');
+    const userContent = parseUserJson(userRaw);
+    const merged = (0, merge_json_1.deepMergeJson)(userContent, templateContent, rule.arrayMerge ?? {});
+    const userStr = JSON.stringify(userContent, null, 2);
+    const mergedStr = JSON.stringify(merged, null, 2);
+    if (userStr === mergedStr) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to} (already up to date)`);
+        return { rule, action: 'noop', path: rule.to };
+    }
+    node_fs_1.default.writeFileSync(dest, `${mergedStr}\n`);
+    const keys = Object.keys(templateContent).join(',');
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to} (merged: ${keys})`);
+    return { rule, action: 'merged', path: rule.to, detail: keys };
+}
+/**
+ * 用 jsonc-parser 读 user 端 JSON 文件，兼容 tsconfig/nest-cli.json 等带 trailing comma 或
+ * 注释的配置。模板侧严格 JSON 走 JSON.parse 也能通，统一走 jsonc 简化代码。
+ */
+function parseUserJson(text) {
+    const errors = [];
+    const parsed = jsonc.parse(text, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+        const first = errors[0];
+        throw new Error(`jsonc parse error ${jsonc.printParseErrorCode(first.error)} at offset ${String(first.offset)}`);
+    }
+    return parsed;
+}
+function syncDirectory(src, dest, overwrite) {
+    if (!node_fs_1.default.existsSync(dest)) {
+        node_fs_1.default.mkdirSync(dest, { recursive: true });
+    }
+    let count = 0;
+    for (const file of node_fs_1.default.readdirSync(src)) {
+        const srcChild = node_path_1.default.join(src, file);
+        const destChild = node_path_1.default.join(dest, file);
+        const stat = node_fs_1.default.statSync(srcChild);
+        if (stat.isDirectory()) {
+            count += syncDirectory(srcChild, destChild, overwrite);
+        }
+        else if (overwrite || !node_fs_1.default.existsSync(destChild)) {
+            node_fs_1.default.copyFileSync(srcChild, destChild);
+            // .sh 自动 +x
+            if (destChild.endsWith('.sh')) {
+                node_fs_1.default.chmodSync(destChild, 0o755);
+            }
+            count++;
+        }
+    }
+    return count;
+}

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.6",
+  "version": "0.1.7-alpha.785a451",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
     "miaoda": "bin/miaoda.js"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "files": [
+    "LICENSE",
+    "README.md",
     "bin",
     "dist",
-    "README.md",
-    "LICENSE"
+    "upgrade"
   ],
   "keywords": [
     "miaoda",
@@ -27,6 +29,7 @@
   "dependencies": {
     "@lark-apaas/http-client": "^0.1.5",
     "commander": "^13.1.0",
+    "jsonc-parser": "^3.3.1",
     "ora": "^5.4.1",
     "picocolors": "^1.1.1"
   },

package/upgrade/templates/README.md

@@ -0,0 +1,34 @@
+# upgrade/templates/
+
+平台管控的脚手架增量内容，按 stack 分目录，由 `miaoda app upgrade` 同步到用户项目。
+
+## 目录约定
+
+```
+upgrade/
+└── templates/
+    └── <stack>/
+        ├── files/                ← 文件模式：按相对路径整文件覆盖
+        │   └── <rel-path>        ← 例如 scripts/dev-local.js → <app>/scripts/dev-local.js
+        └── patches/              ← JSON merge 模式：按相对路径 deep merge（任意 JSON 文件）
+            └── <rel-path>.json   ← 例如 package.json / tsconfig.json / nest-cli.json
+```
+
+## 同步行为
+
+- **files/**：递归遍历，按相对路径全量覆盖 targetDir。`.sh` 后缀文件同步后自动 `chmod +x`。
+- **patches/**：递归遍历，**每个 `.json` 文件** 都跟 targetDir 同路径文件做 deep merge：
+  - 两边都必须是 JSON object（否则报错）
+  - value 是 object → 递归 merge；value 是数组 / 标量 → 整体替换
+  - 目标文件不存在则报错（patches 是补丁性质，不负责创建文件；app init 应该先创建）
+  - patches 下非 `.json` 文件会被跳过（预留给将来其它 patch 类型）
+- 不做用户改动保护（本期约定：`upgrade/templates/` 下的文件路径由平台拥有，用户不应手改）。
+
+## 跟 `miaoda skills sync` 的区别
+
+| 链路 | 源 | 内容 | 目标 |
+|---|---|---|---|
+| `miaoda skills sync` | NPM 包 `@lark-apaas/coding-steering` | agent skills（`.md`） | `<app>/.agent/skills/steering/<stack>/` |
+| `miaoda app upgrade`  | 本仓 `upgrade/templates/<stack>/` | 启动脚本、package.json 字段等 | `<app>/` 项目根 |
+
+两者独立调用，互不依赖。

package/upgrade/templates/design-stack/templates/.githooks/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+[ "$SKIP_GIT_HOOKS" = "1" ] && exit 0
+export PATH="node_modules/.bin:$PATH"
+npm run precommit

package/upgrade/templates/design-stack/templates/scripts/dev-local.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// ============================================================================
+// 本地开发启动脚本（由 miaoda app sync 维护，请勿手改）
+// Stack: design-stack
+//
+// 流程:
+//   1. env pull —— 拉沙箱身份/凭证到 .env.local
+//   2. skills sync —— 同步当前 stack 的 agent skills
+//   3. dotenv 加载 .env / .env.local 到 process.env（含 SUDA_WEBUSER 适配）
+//   4. 起单进程 dev server（design-stack 单进程，无 server/client 拆分）
+//
+// 设计同 nestjs-react-fullstack/dev-local.js,SDK 包不需要自己 require('dotenv'),
+// env 加载收敛在启动脚本单点。SUDA_WEBUSER 适配同 nrf 那份。
+// ============================================================================
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, spawn, spawnSync } = require('node:child_process');
+
+process.chdir(path.resolve(__dirname, '..'));
+
+function warn(msg) {
+  if (process.stderr.isTTY) process.stderr.write(`\x1b[33mWARNING: ${msg}\x1b[0m\n`);
+  else process.stderr.write(`WARNING: ${msg}\n`);
+}
+
+if (!process.env.MIAODA_APP_TYPE) process.env.MIAODA_APP_TYPE = '4';
+process.env.MIAODA_LOCAL_DEV = '1';
+
+console.log('[dev-local] (1/4) env pull...');
+const hasLarkCli = spawnSync('command', ['-v', 'lark-cli'], { shell: true, stdio: 'ignore' }).status === 0;
+if (hasLarkCli) {
+  let appId = '';
+  try {
+    appId = JSON.parse(fs.readFileSync('.spark/meta.json', 'utf8')).app_id || '';
+  } catch {
+    /* meta.json 不存在或非法 JSON */
+  }
+  if (appId) {
+    const r = spawnSync('lark-cli', ['apps', '+env-pull', '--app-id', appId, '--as', 'user'], {
+      stdio: 'inherit',
+    });
+    if (r.status !== 0) warn('env pull 失败，继续按 .env.local 现状启动');
+  } else {
+    warn('.spark/meta.json 缺 app_id，请先跑 `miaoda app init --app-id <id>`');
+  }
+} else {
+  warn('lark-cli 未安装，跳过 env pull；请确保 .env.local 已就绪');
+}
+
+// skills sync —— --local 切 flat layout;临时钉 @alpha,等 0.1.7 发到 latest 后切回。
+console.log('[dev-local] (2/4) miaoda skills sync...');
+try {
+  execSync('npx -y @lark-apaas/miaoda-cli@alpha skills sync --local', { stdio: 'inherit' });
+} catch {
+  console.log('  (skills sync 失败，继续启动)');
+}
+
+console.log('[dev-local] (3/4) loading .env / .env.local...');
+const dotenv = require('dotenv');
+dotenv.config({ path: '.env.local' });
+dotenv.config({ path: '.env' });
+
+if (process.env.SUDA_WEBUSER) {
+  const raw = process.env.SUDA_WEBUSER;
+  try {
+    JSON.parse(raw);
+  } catch {
+    try {
+      const unescaped = raw.replace(/\\"/g, '"');
+      JSON.parse(unescaped);
+      process.env.SUDA_WEBUSER = unescaped;
+    } catch {
+      warn(`SUDA_WEBUSER 解析失败,值头部: ${raw.slice(0, 80)}...`);
+    }
+  }
+}
+
+console.log('[dev-local] (4/4) npm run dev');
+const child = spawn('npm', ['run', 'dev'], { stdio: 'inherit', env: process.env });
+child.on('exit', (code) => process.exit(code ?? 0));
+child.on('error', (err) => {
+  console.error(err);
+  process.exit(1);
+});