@lark-apaas/miaoda-cli 0.1.4 → 0.1.5-alpha.2f1e0ff

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/spark-meta.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSparkMeta = readSparkMeta;
+exports.writeSparkMeta = writeSparkMeta;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SPARK_DIR = '.spark';
+const SPARK_META_FILE = 'meta.json';
+function readSparkMeta(appDir) {
+    const metaPath = node_path_1.default.join(appDir, SPARK_DIR, SPARK_META_FILE);
+    if (!node_fs_1.default.existsSync(metaPath))
+        return {};
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * merge 写入：已有字段保留，undefined 不覆盖；不再维护时间戳。
+ */
+function writeSparkMeta(appDir, meta) {
+    const sparkDir = node_path_1.default.join(appDir, SPARK_DIR);
+    node_fs_1.default.mkdirSync(sparkDir, { recursive: true });
+    const metaPath = node_path_1.default.join(sparkDir, SPARK_META_FILE);
+    let existing = {};
+    if (node_fs_1.default.existsSync(metaPath)) {
+        try {
+            existing = JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf-8'));
+        }
+        catch {
+            /* 读不出就当空 */
+        }
+    }
+    const defined = Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined));
+    const merged = { ...existing, ...defined };
+    node_fs_1.default.writeFileSync(metaPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}

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,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.4",
+  "version": "0.1.5-alpha.2f1e0ff",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -10,10 +10,11 @@
     "access": "public"
   },
   "files": [
+    "LICENSE",
+    "README.md",
     "bin",
     "dist",
-    "README.md",
-    "LICENSE"
+    "upgrade"
   ],
   "keywords": [
     "miaoda",
@@ -27,6 +28,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.sh → <app>/scripts/dev-local.sh
+        └── 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.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# ============================================================================
+# 本地 dev 启动脚本(平台控制,通过 `miaoda app upgrade` 同步,请勿手改)
+# Stack: design-stack(SSR-only,无 server 业务逻辑,无数据库)
+# 流程:env pull → skills sync → 起 dev server
+# ============================================================================
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT_DIR"
+
+# Stack 是 design-stack,对应 miaoda CLI 的 design scene
+# 沙箱里这个 env 由平台注入,本地 dev 由本脚本兜底,确保 miaoda 子命令(skills/sync)能看见
+export MIAODA_APP_TYPE="${MIAODA_APP_TYPE:-4}"
+
+# 本地开发总开关:SDK 据此启用本地兜底逻辑(view-context 占位填充 / __runtime__ 反代 / csrf+webuser)
+# 沙箱 dev / 生产不设此 env,SDK 行为完全不变
+export MIAODA_LOCAL_DEV=1
+
+# 临时:绕 npmmirror/bnpm 内网到 npmjs 的同步延迟,等 coding-steering 正式版去掉
+export MIAODA_NPM_REGISTRY="${MIAODA_NPM_REGISTRY:-https://registry.npmjs.org/}"
+
+# === .env.local / .env 加载由 SDK 侧负责，本脚本不再手工 source ===
+# fullstack-nestjs-core 在 module init 通过 dotenv 读 .env.local + .env；
+# fullstack-{vite,rspack}-preset 的 defineConfig 同理。优先级:shell > .env.local > .env。
+
+# 1. 拉本地 dev 所需 ENV(jwt / cookie 等,写入 .env.local)
+#    app_id 从 .spark/meta.json 读 —— `miaoda app init --app-id <id>` 时持久化的权威源,
+#    后续 dev / sync 全部沿用这一个值;不在脚本里 hack 别的推断渠道。
+#    lark-cli 子命令真名是 `+env-pull`（带 + 前缀单 token,不是 `env pull` 空格分隔）;
+#    `--as user` 必须显式:env-pull 只接受 user identity,默认 bot 会校验失败。
+echo "[dev-local] (1/3) env pull..."
+if command -v lark-cli >/dev/null 2>&1; then
+  # 用 node 读 .spark/meta.json,不引 python3 依赖(user app 必装 node)。
+  APP_ID=$(node -e 'try{process.stdout.write(JSON.parse(require("fs").readFileSync(".spark/meta.json","utf8")).app_id||"")}catch(e){}' 2>/dev/null || echo "")
+  if [ -n "$APP_ID" ]; then
+    lark-cli apps +env-pull --app-id "$APP_ID" --as user || echo "  (env pull 失败,后续按 .env.local 现状继续)"
+  else
+    echo "  (.spark/meta.json 缺 app_id,先跑 \`miaoda app init --app-id <id>\` 写入)"
+  fi
+else
+  echo "  (lark-cli 未装,跳过 env pull;请确保 .env.local 已就绪)"
+fi
+
+# 2. 同步 stack 对应 skills(coding-steering)。走 npx 不依赖用户全局装 miaoda;
+#    钉到 @alpha dist-tag 跟随最新发布,miaoda-cli 通道我们自己控制风险小。
+echo "[dev-local] (2/3) miaoda skills sync..."
+npx -y @lark-apaas/miaoda-cli@alpha skills sync || echo "  (skills sync 失败,继续启动)"
+
+# 3. 起 dev server(design-stack 只有 SSR 渲染,单进程即可;不走 scripts/dev.js 的保活)
+#    如果模板的 npm run dev 本身就是裸进程(无保活)则直接调即可;
+#    如果 design-stack 模板的 dev 也是 dev.js 包装,后续需要新增 dev:raw 之类的直通命令
+echo "[dev-local] (3/3) npm run dev"
+exec npm run dev

package/upgrade/templates/design-stack/templates/scripts/dev.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# `npm run dev` 入口；按 SANDBOX_ID 是否非空判断运行环境：
+#   - SANDBOX_ID 非空（沙箱平台注入应用所属沙箱 ID）→ 直接跑 dev.js
+#       （保活 / restart loop / 文件日志 —— 沙箱生产形态）。脚本同步由平台 pod 启动阶段做过，
+#       dev 入口不再额外 `npm run upgrade`。
+#   - 否则（本地）→ 走 miaoda app sync 兜底 + 跑 dev-local.sh：纯 stdout、崩了就崩、Agent 友好。
+# 显式想跑本地路径可用 `npm run dev:local`（绕过 SANDBOX_ID 判断）。
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -n "${SANDBOX_ID:-}" ]; then
+  exec node "$SCRIPT_DIR/dev.js" "$@"
+fi
+
+if [ ! -x "$SCRIPT_DIR/dev-local.sh" ]; then
+  echo "[dev] scripts/dev-local.sh 缺失或不可执行；先跑 \`npx -y @lark-apaas/miaoda-cli@alpha app sync\` 同步平台脚本" >&2
+  exit 1
+fi
+
+# 本地启动前先跑一次 miaoda app sync：同步 platform-controlled 内容 + 升 @lark-apaas/* 到
+# 钉版 + 迁移老 npm scripts。沙箱不走这里（SANDBOX_ID 分支已经 exec return）。
+# 走 npx 不依赖用户全局装 miaoda；钉到 @alpha dist-tag 跟随最新发布。
+npx -y @lark-apaas/miaoda-cli@alpha app sync || echo "[dev] miaoda app sync 失败，按现状继续" >&2
+
+exec "$SCRIPT_DIR/dev-local.sh" "$@"