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

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

@@ -0,0 +1,266 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAppUpgrade = void 0;
+exports.handleAppSync = handleAppSync;
+exports.runStackSync = runStackSync;
+exports.summarizeSyncResults = summarizeSyncResults;
+exports.listManagedDeps = listManagedDeps;
+exports.upgradePlatformDeps = upgradePlatformDeps;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const sync_configs_1 = require("../../../config/sync-configs");
+const sync_rule_1 = require("../../../utils/sync-rule");
+const platform_sync_1 = require("../../../utils/platform-sync");
+const githooks_1 = require("../../../utils/githooks");
+const install_1 = require("../../../services/app/init/install");
+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 sync` / `miaoda app init` 管控的平台包白名单 —— user app 已装这些包时，
+ * sync 把 package.json 里的版本规范统一改写成 `"latest"`，npm install 时解析到当前 latest。
+ *
+ * 白名单外的 @lark-apaas/* 包：sync 不动；user app 未装的包：sync 不引入。
+ *
+ * 之前曾按表钉死具体 alpha 版本（避免外部 prerelease 回归），上线切 latest 通道后简化为
+ * 仅维护包名白名单。若某个包出现回归需要临时止血，把对应行从 `"latest"` 改为具体版本号
+ * 即可（用 Record<string, string> 结构而不是 Set，保留这个 escape hatch 的可能性）。
+ */
+const MANAGED_PLATFORM_PACKAGES = {
+    '@lark-apaas/auth-sdk': 'latest',
+    '@lark-apaas/client-toolkit': 'latest',
+    '@lark-apaas/client-toolkit-lite': 'latest',
+    '@lark-apaas/dataloom': 'latest',
+    '@lark-apaas/db-schema-sync': 'latest',
+    '@lark-apaas/express-core': 'latest',
+    '@lark-apaas/fullstack-cli': 'latest',
+    '@lark-apaas/fullstack-nestjs-core': 'latest',
+    '@lark-apaas/fullstack-rspack-preset': 'latest',
+    '@lark-apaas/fullstack-vite-preset': 'latest',
+    '@lark-apaas/http-client': 'latest',
+};
+/**
+ * miaoda app sync [--dir <path>]
+ *
+ * 一站式同步：把当前 stack 的 sync 规则全套 apply 到 user app，对齐沙箱里
+ * `npm run upgrade → npx fullstack-cli sync` 的行为，并补 miaoda-cli 本地开发独有规则。
+ *
+ * 执行流：
+ *   1. SyncRule[] 全量 apply —— 来自 src/config/sync-configs/<stack>.ts。每个 stack
+ *      自带模板资源在 upgrade/templates/<stack>/templates/。表里没有该 stack 时回退到
+ *      旧 platform-sync 兜底（兼容尚未迁移的 stack）。
+ *   2. 平台 deps 指 latest —— user app 已装的 @lark-apaas/* 按 MANAGED_PLATFORM_PACKAGES
+ *      白名单改写为 "latest"（紧急止血时表里可填具体版本）。
+ *   3. activateGitHooks —— 设置 core.hooksPath（template 自带 .githooks/pre-commit）。
+ *   4. npm install --no-audit --no-fund --ignore-scripts —— 物化新版本，绕开
+ *      action-plugin postinstall 在缺平台 env 时的 ENOENT。
+ *
+ * 需要 .spark/meta.json 已含 stack（走过 `miaoda app init`）。
+ * 不动 .agent/skills/（那是 `miaoda skills sync` 的事）。
+ */
+async function handleAppSync(opts) {
+    await Promise.resolve();
+    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+    if (meta.stack === undefined || meta.stack === '') {
+        throw new error_1.AppError('SYNC_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+    }
+    // 1. apply SyncRule[]，stack 没注册时回退到旧 platform-sync 兜底；都不识别就报错
+    const syncResults = runStackSync(meta.stack, targetDir, 'sync');
+    if (!syncResults.stackFound) {
+        throw new error_1.AppError('SYNC_STACK_NOT_SUPPORTED', `stack '${meta.stack}' has no SyncConfig and no upgrade/templates/${meta.stack}/ — 该 stack 暂未纳入 sync 范围`, {
+            next_actions: [
+                `src/config/sync-configs/${meta.stack}.ts 加 SyncConfig 并在 STACK_REGISTRY 注册`,
+            ],
+        });
+    }
+    // 2. @lark-apaas/* dep 统一指 latest（按 MANAGED_PLATFORM_PACKAGES 白名单，user app 已装才升）
+    const upgradedPackages = upgradePlatformDeps(targetDir, 'sync');
+    // 3. activate git hooks（template 自带 .githooks/pre-commit，core.hooksPath 一次性设置）
+    const hookActivation = (0, githooks_1.activateGitHooks)(targetDir);
+    // 4. npm install —— 跟 init 一样软失败,install 挂了不该阻断 emit / sync 总结输出。
+    // 把 user app 装着的**所有**管控包显式作为位置参数传给 npm install,强制 npm 重新
+    // resolve lockfile entry。原因:
+    //   - 即便 package.json spec 已经是 "latest"(没有 from→to 变化),user app 老 lockfile
+    //     可能锁着具体老版本 (如 fullstack-vite-preset@1.0.9),纯 `npm install` 会按 lockfile
+    //     拉老版,绕过 spec "latest" 的解析意图
+    //   - 显式 `npm install foo@latest bar@latest` 让 npm 重新解析,lockfile 跟着更新到当前 latest
+    //   - 没装的管控包不动 (sync 的职责是对齐,不是塞依赖)
+    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT。
+    // --registry 跟 init 钉同一份 npmmirror,避免 user 全局 ~/.npmrc 把 sync 拉到另一个源
+    // (详见 services/app/init/install.ts 上的注释)。MIAODA_NPM_REGISTRY env 兜底。
+    const installArgs = [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--ignore-scripts',
+        '--registry',
+        (0, install_1.resolveNpmInstallRegistry)(),
+    ];
+    for (const name of listManagedDeps(targetDir)) {
+        installArgs.push(`${name}@${MANAGED_PLATFORM_PACKAGES[name]}`);
+    }
+    (0, logger_1.log)('sync', `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)('sync', `⚠ npm install failed (continuing): ${installError}`);
+    }
+    (0, output_1.emit)({
+        data: {
+            stack: meta.stack,
+            ...summarizeSyncResults(syncResults),
+            upgradedPackages,
+            gitHooks: hookActivation.action,
+            installError,
+        },
+    });
+}
+/** 老命令 `miaoda app upgrade` 的 handler 名，保留为 sync handler 的 alias。 */
+exports.handleAppUpgrade = handleAppSync;
+/**
+ * 给 stack 应用 sync rules（sync handler + init handler 共用）。
+ * stack 在 STACK_REGISTRY 注册时走新 SyncRule 机制，否则回落到旧 platform-sync。
+ *
+ * stack 完全不识别（既不在 STACK_REGISTRY 也无 upgrade/templates/<stack>/ 目录）时返回
+ * `stackFound: false` 而非抛错 —— 让调用方按场景决定：sync handler 抛 AppError，init handler
+ * 允许（fresh init 时 stack 还在加注册的过渡期）。
+ */
+function runStackSync(stack, targetDir, logPrefix) {
+    const config = (0, sync_configs_1.getSyncConfig)(stack);
+    if (config !== null) {
+        const sourceRoot = (0, sync_configs_1.getStackTemplatesRoot)(stack);
+        if (!node_fs_1.default.existsSync(sourceRoot)) {
+            throw new error_1.AppError('SYNC_TEMPLATES_MISSING', `upgrade/templates/${stack}/templates/ not found at ${sourceRoot} — cli 安装异常?`);
+        }
+        (0, logger_1.log)(logPrefix, `Applying ${config.sync.length.toString()} sync rule(s) for stack '${stack}'`);
+        const rulesApplied = (0, sync_rule_1.applySyncRules)(config.sync, { sourceRoot, targetDir, logPrefix });
+        return { stackFound: true, rulesApplied };
+    }
+    // fallback：表外 stack 仍用旧 platform-sync 机制（files/ overlay + patches/ deep merge）
+    (0, logger_1.log)(logPrefix, `Stack '${stack}' not in new sync registry, falling back to legacy platform-sync`);
+    const legacy = (0, platform_sync_1.syncPlatformControlled)({ stack, targetDir, logPrefix });
+    return {
+        stackFound: legacy.stackFound,
+        rulesApplied: [],
+        legacy: { syncedFiles: legacy.syncedFiles, mergedJsonFiles: legacy.mergedJsonFiles },
+    };
+}
+/** 把 SyncRuleResult[] / legacy 输出汇总成 emit data 里的几组字段，便于诊断。 */
+function summarizeSyncResults(result) {
+    if (result.legacy !== undefined) {
+        return {
+            appliedRules: [],
+            syncedFiles: result.legacy.syncedFiles,
+            mergedJsonFiles: result.legacy.mergedJsonFiles,
+            patchedScripts: [],
+        };
+    }
+    const appliedRules = result.rulesApplied.map((r) => ({
+        type: r.rule.type,
+        action: r.action,
+        path: r.path,
+        detail: r.detail,
+    }));
+    const syncedFiles = [];
+    for (const r of result.rulesApplied) {
+        if ((r.action === 'synced' || r.action === 'created') && r.path !== undefined) {
+            syncedFiles.push(r.path);
+        }
+    }
+    const mergedJsonFiles = [];
+    for (const r of result.rulesApplied) {
+        if (r.rule.type !== 'merge-json')
+            continue;
+        if (r.action !== 'merged' && r.action !== 'created')
+            continue;
+        if (r.path === undefined)
+            continue;
+        mergedJsonFiles.push({
+            path: r.path,
+            keys: r.detail !== undefined ? r.detail.split(',').filter(Boolean) : [],
+        });
+    }
+    const patchedScripts = result.rulesApplied
+        .filter((r) => (r.rule.type === 'patch-script' || r.rule.type === 'add-script') &&
+        (r.action === 'patched' || r.action === 'created'))
+        .map((r) => r.rule.name);
+    return { appliedRules, syncedFiles, mergedJsonFiles, patchedScripts };
+}
+function readPackageJson(pkgJsonPath) {
+    if (!node_fs_1.default.existsSync(pkgJsonPath))
+        return null;
+    return JSON.parse(node_fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));
+}
+/**
+ * 列出 user app 装着的 @lark-apaas/* 管控包 (在 MANAGED_PLATFORM_PACKAGES 白名单内的)。
+ * sync handler 用来给 `npm install` 显式列管控包名 + @latest,强制 npm 重新 resolve
+ * lockfile entry —— 即便 package.json spec 已经是 "latest" 没 from→to 变化,
+ * 老 lockfile 锁的具体老版本(如 fullstack-vite-preset@1.0.9)也会被刷掉。
+ */
+function listManagedDeps(targetDir) {
+    const pkg = readPackageJson(node_path_1.default.join(targetDir, 'package.json'));
+    if (!pkg)
+        return [];
+    const names = new Set();
+    for (const section of ['dependencies', 'devDependencies']) {
+        const deps = pkg[section];
+        if (!deps || typeof deps !== 'object')
+            continue;
+        for (const name of Object.keys(deps)) {
+            if (Object.prototype.hasOwnProperty.call(MANAGED_PLATFORM_PACKAGES, name)) {
+                names.add(name);
+            }
+        }
+    }
+    return [...names];
+}
+/**
+ * 把 user app package.json 里已装的 @lark-apaas/* 平台包改写成 MANAGED_PLATFORM_PACKAGES
+ * 表里的目标 spec（缺省 `"latest"`）。由 `miaoda app sync` 和 `miaoda app init`（template
+ * 渲染后、install 之前）共用。
+ *
+ * - user app 已装的管控包 → 写表里的目标 spec（默认 latest，紧急止血时可改具体版本）
+ * - user app 未装的管控包 → 不引入（sync 的职责是对齐，不是塞依赖）
+ * - 装着但不在白名单的 @lark-apaas/* 包 → 完全不动
+ *
+ * @param logPrefix 用于 `[<prefix>]   deps.xxx: a → b` 日志前缀；sync 流程传 'sync'，init 流程传 'init'。
+ */
+function upgradePlatformDeps(targetDir, logPrefix = 'sync') {
+    const pkgJsonPath = node_path_1.default.join(targetDir, 'package.json');
+    const pkg = readPackageJson(pkgJsonPath);
+    if (!pkg)
+        return [];
+    const updated = [];
+    for (const section of ['dependencies', 'devDependencies']) {
+        const deps = pkg[section];
+        if (!deps || typeof deps !== 'object')
+            continue;
+        for (const name of Object.keys(deps)) {
+            if (!Object.prototype.hasOwnProperty.call(MANAGED_PLATFORM_PACKAGES, name))
+                continue;
+            const target = MANAGED_PLATFORM_PACKAGES[name];
+            const from = deps[name];
+            if (from === target)
+                continue;
+            deps[name] = target;
+            updated.push({ name, from, to: target, section });
+            (0, logger_1.log)(logPrefix, `  ${section}.${name}: ${from} → ${target}`);
+        }
+    }
+    if (updated.length > 0) {
+        node_fs_1.default.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    return updated;
+}

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/cli/handlers/plugin/plugin-local.js

@@ -76,7 +76,7 @@ function parsePluginName(input) {
     if (!match) {
         throw new error_1.AppError('INVALID_PLUGIN_NAME', `Invalid plugin name format: ${input}. Expected: @scope/name or @scope/name@version`, { next_actions: ['示例：@demo/example-plugin 或 @demo/example-plugin@1.2.3'] });
     }
-    return { name: match[1], version: match[2] ?? 'latest' };
+    return { name: match[1], version: match[2] || 'latest' };
 }
 // ── package.json actionPlugins CRUD ──
 function readPackageJson() {

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

@@ -10,10 +10,10 @@ const spark_meta_1 = require("../../../utils/spark-meta");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 /**
- * miaoda skills sync [--dir <path>] [--version <ver>]
+ * miaoda skills sync [version] [--dir <path>]
  *
- * 从 .spark/meta.json 读 stack，把 coding-steering 包内对应 stack 的 skills + tech.md
- * 同步到 <dir>/.agent/steering/。需要先跑过 `miaoda app init`。
+ * 从 .spark/meta.json 读 stack（+ 默认 steeringVersion），把 coding-steering 包内对应 stack
+ * 的 skills + tech.md 同步到 <dir>/.agent/steering/。需要先跑过 `miaoda app init`。
  */
 async function handleSkillsSync(opts) {
     await Promise.resolve();
@@ -22,17 +22,28 @@ async function handleSkillsSync(opts) {
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('SKILLS_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
     }
+    const version = opts.version ?? meta.steeringVersion;
+    const versionSource = opts.version
+        ? 'cli-arg'
+        : meta.steeringVersion
+            ? 'meta.json'
+            : 'default-latest';
     const result = (0, coding_steering_1.syncCodingSteering)({
         stack: meta.stack,
         targetDir,
-        version: opts.version,
+        version,
+        outputLayout: opts.local === true ? 'flat' : 'nested',
     });
     (0, output_1.emit)({
         data: {
             stack: meta.stack,
             version: result.version,
+            versionSource,
             syncedSkills: result.syncedSkills,
             techSynced: result.techSynced,
+            ...(result.claudeSkillsLink !== undefined
+                ? { claudeSkillsLink: result.claudeSkillsLink }
+                : {}),
         },
     });
 }

package/dist/config/fullstack-cli-pin.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FULLSTACK_CLI_PIN_SPEC = void 0;
+/**
+ * `@lark-apaas/fullstack-cli` 的 npx 调用 spec。
+ *
+ * 用于 user app `package.json` 里所有 `npx -y @lark-apaas/fullstack-cli ...` 调用 ——
+ * sync 规则会按本常量生成 `npx -y <FULLSTACK_CLI_PIN_SPEC> ...`。常量化是为了：
+ *   - 跟 src/cli/handlers/app/sync.ts 里 MANAGED_PLATFORM_PACKAGES['@lark-apaas/fullstack-cli']
+ *     的 spec 保持一致（user app deps 跟 npm script 里 npx 调用同步切渠道）
+ *   - 紧急止血时改一行就能把所有 user app 的 npm script 改回钉版（例如 `@1.1.49-alpha.0`）
+ */
+exports.FULLSTACK_CLI_PIN_SPEC = '@lark-apaas/fullstack-cli@latest';

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

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * design-stack 的 sync 规则。
+ *
+ * design-stack 是 SSR-only 全栈 stack（design scene，MIAODA_APP_TYPE=4），无 nest 后端、
+ * 无数据库、无 nestjs-cli。所以规则集是 nestjs-react-fullstack 的子集：只保留
+ * scripts/.githooks/ 派生 + 基础 npm scripts，不动 nest-cli.json / drizzle / tsconfig.node.json。
+ *
+ * dev-local.js 跟 nestjs-react-fullstack 不同（单进程 npm run dev，MIAODA_APP_TYPE=4），
+ * 单独维护在 upgrade/templates/design-stack/templates/scripts/dev-local.js。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_CONFIG = void 0;
+const fullstack_cli_pin_1 = require("../../config/fullstack-cli-pin");
+exports.SYNC_CONFIG = {
+    sync: [
+        // 1. 派生 scripts/（含 design 专属 dev-local.js + 通用 dev.sh / hooks/run-precommit.js）
+        {
+            type: 'directory',
+            from: 'scripts',
+            to: 'scripts',
+            overwrite: true,
+        },
+        // 1a. 同步 .githooks/（hook 入口，可执行 sh）
+        {
+            type: 'directory',
+            from: '.githooks',
+            to: '.githooks',
+            overwrite: true,
+        },
+        // 1b. scripts.prepare：npm install 后激活 git hooks
+        {
+            type: 'add-script',
+            name: 'prepare',
+            command: 'chmod +x .githooks/pre-commit 2>/dev/null; git config core.hooksPath .githooks 2>/dev/null || true',
+            overwrite: false,
+        },
+        // 1c. scripts.precommit
+        {
+            type: 'add-script',
+            name: 'precommit',
+            command: 'node scripts/hooks/run-precommit.js',
+            overwrite: false,
+        },
+        // 2. .gitignore 卫生：移除 package-lock.json + 加 .agent/
+        {
+            type: 'remove-line',
+            to: '.gitignore',
+            pattern: 'package-lock.json',
+        },
+        {
+            type: 'add-line',
+            to: '.gitignore',
+            line: '.agent/',
+        },
+        // 3. 老 npm scripts 迁移（裸 fullstack-cli → 钉版 npx）。两条 ifStartsWith 分别覆盖
+        //    "裸 fullstack-cli"（最老形态）和 "npx 未钉版" 形态，统一升到 FULLSTACK_CLI_PIN_SPEC。
+        {
+            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',
+        },
+        {
+            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',
+        },
+        {
+            type: 'patch-script',
+            name: 'upgrade',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
+            ifStartsWith: 'fullstack-cli sync',
+        },
+        {
+            type: 'patch-script',
+            name: 'upgrade',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
+            ifStartsWith: 'npx -y @lark-apaas/fullstack-cli sync',
+        },
+        {
+            type: 'patch-script',
+            name: 'dev',
+            to: './scripts/dev.sh',
+            ifStartsWith: 'npm run upgrade && ',
+        },
+        // ===== miaoda-cli 本地开发新增规则 =====
+        // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
+        {
+            type: 'add-script',
+            name: 'dev:local',
+            command: 'node ./scripts/dev-local.js',
+            overwrite: false,
+        },
+    ],
+};
+exports.default = exports.SYNC_CONFIG;

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

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * 按 stack 短名拿到对应的 SyncConfig + 模板源根目录。
+ *
+ * - 类型化的 SyncConfig 放在 src/config/sync-configs/<stack>.ts（被 tsc 编进 dist 一起发）。
+ * - 模板资源文件放在 upgrade/templates/<stack>/templates/（cli 发布时整个目录原样 ship）。
+ *
+ * handler 拿到 stack 后，先 getSyncConfig 拿 rule 列表，再 getStackTemplatesRoot 拿模板根，
+ * 一起喂给 applySyncRules。
+ *
+ * 新加 stack：
+ *   1. src/config/sync-configs/<stack>.ts 里 export default SYNC_CONFIG
+ *   2. upgrade/templates/<stack>/templates/ 下放对应资源文件
+ *   3. 在 STACK_REGISTRY 里加一条
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSyncConfig = getSyncConfig;
+exports.getStackTemplatesRoot = getStackTemplatesRoot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const nestjs_react_fullstack_1 = __importDefault(require("./nestjs-react-fullstack"));
+const design_stack_1 = __importDefault(require("./design-stack"));
+/**
+ * 已纳入新 sync 机制的 stack 注册表。未在表里的 stack（如老 vite-react / html）走旧的
+ * `upgrade/templates/<stack>/{files,patches}` 机制，由 sync handler 兜底。
+ */
+const STACK_REGISTRY = {
+    'nestjs-react-fullstack': nestjs_react_fullstack_1.default,
+    'design-stack': design_stack_1.default,
+};
+/** 返回该 stack 的 SyncConfig；表里没有时返回 null。 */
+function getSyncConfig(stack) {
+    return STACK_REGISTRY[stack] ?? null;
+}
+/**
+ * 计算 stack 模板资源根目录（绝对路径）。
+ *
+ * cli 发布时 upgrade/ 目录整个 ship，编译产物在 dist/ 下若干层。从当前模块向上回溯找含
+ * upgrade/ + package.json 的目录就是 cli 根。
+ *
+ * 跟 utils/platform-sync.ts 同款 pattern；保持对齐避免两边漂移。
+ */
+function getStackTemplatesRoot(stack) {
+    return node_path_1.default.join(findCliRoot(), 'upgrade', 'templates', stack, 'templates');
+}
+let cliRootCache = null;
+function findCliRoot() {
+    if (cliRootCache !== null)
+        return cliRootCache;
+    let dir = __dirname;
+    while (dir !== node_path_1.default.dirname(dir)) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, 'upgrade')) && node_fs_1.default.existsSync(node_path_1.default.join(dir, 'package.json'))) {
+            cliRootCache = dir;
+            return dir;
+        }
+        dir = node_path_1.default.dirname(dir);
+    }
+    throw new Error(`miaoda-cli root (containing upgrade/) not found from ${__dirname}`);
+}