@lark-apaas/miaoda-cli 0.1.3 → 0.1.4-alpha.abaa17f

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

@@ -16,12 +16,12 @@ const COMMON_TIME_HELP = `
 `;
 function registerObservabilityCommands(program) {
     const obCmd = program
-        .command("observability")
-        .description("可观测性：查询线上日志、链路、监控指标、运营指标");
+        .command('observability')
+        .description('可观测性：查询线上日志、链路、监控指标、运营指标');
     obCmd.action(() => {
         obCmd.outputHelp();
     });
-    obCmd.addHelpText("after", `
+    obCmd.addHelpText('after', `
 作用范围
   仅供 Agent 在妙搭沙箱内调用，查询当前应用的线上观测数据。所有命令为只读。
   应用上下文：--app-id <id> 或环境变量 MIAODA_APP_ID。
@@ -37,26 +37,26 @@ function registerObservabilityCommands(program) {
 // ── log ──
 function registerLog(parent) {
     const cmd = parent
-        .command("log")
-        .description("查询线上运行日志（按时间倒序，分页）")
+        .command('log')
+        .description('查询线上运行日志（按时间倒序，分页）')
         .addOption((0, shared_1.appIdOption)().hideHelp())
-        .addOption(new commander_1.Option("--level <level>", "日志级别（大小写不敏感）")
-        .choices(["DEBUG", "INFO", "WARN", "ERROR"])
-        .argParser((0, shared_1.caseInsensitiveChoice)(["DEBUG", "INFO", "WARN", "ERROR"])))
-        .option("--since <time>", "开始时间")
-        .option("--until <time>", "截止时间")
-        .option("--log-id <id>", "按请求 logid 过滤（attributes.ob_data_id）")
-        .option("--trace-id <id>", "按 trace ID 过滤")
-        .option("--grep <pattern>", "按关键字模糊搜索 body")
-        .option("--module <name>", "按模块名过滤")
-        .option("--user-id <user-id>", "按触发用户 ID 过滤")
-        .option("--page <path>", "按页面路径过滤")
-        .option("--api <path>", "按接口路径过滤")
-        .option("--min-duration <ms>", "最小耗时过滤（毫秒）")
-        .option("--max-duration <ms>", "最大耗时过滤（毫秒）")
-        .option("--limit <n>", "返回条数上限（1~100）", parseLimit, 50)
-        .option("--cursor <token>", "下一页游标，从上一次返回的 next_cursor 取值")
-        .addHelpText("after", `${COMMON_TIME_HELP}
+        .addOption(new commander_1.Option('--level <level>', '日志级别（大小写不敏感）')
+        .choices(['DEBUG', 'INFO', 'WARN', 'ERROR'])
+        .argParser((0, shared_1.caseInsensitiveChoice)(['DEBUG', 'INFO', 'WARN', 'ERROR'])))
+        .option('--since <time>', '开始时间')
+        .option('--until <time>', '截止时间')
+        .option('--log-id <id>', '按请求 logid 过滤（attributes.ob_data_id）')
+        .option('--trace-id <id>', '按 trace ID 过滤')
+        .option('--grep <pattern>', '按关键字模糊搜索 body')
+        .option('--module <name>', '按模块名过滤')
+        .option('--user-id <user-id>', '按触发用户 ID 过滤')
+        .option('--page <path>', '按页面路径过滤')
+        .option('--api <path>', '按接口路径过滤')
+        .option('--min-duration <ms>', '最小耗时过滤（毫秒）')
+        .option('--max-duration <ms>', '最大耗时过滤（毫秒）')
+        .option('--limit <n>', '返回条数上限（1~100）', parseLimit, 50)
+        .option('--cursor <token>', '下一页游标，从上一次返回的 next_cursor 取值')
+        .addHelpText('after', `${COMMON_TIME_HELP}
 JSON 输出
   {"data": [...], "next_cursor": "...", "has_more": true|false}
 
@@ -67,8 +67,8 @@ JSON 输出
   $ miaoda observability log --api /api/orders --min-duration 200 --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
-        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
-        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        (0, shared_1.validateTimeOptions)(rawOpts, 'since', 'until');
+        (0, shared_1.rejectCliOverride)(cmd, 'appId');
         await (0, index_1.handleObservabilityLog)({
             appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             level: rawOpts.level,
@@ -90,22 +90,22 @@ JSON 输出
 }
 // ── trace ──
 function registerTrace(parent) {
-    const traceCmd = parent.command("trace").description("链路追踪：列表 / 详情");
+    const traceCmd = parent.command('trace').description('链路追踪：列表 / 详情');
     traceCmd.action(() => {
         traceCmd.outputHelp();
     });
     const listCmd = traceCmd
-        .command("list")
-        .description("查询线上链路列表（按链路时间倒序，分页）")
+        .command('list')
+        .description('查询线上链路列表（按链路时间倒序，分页）')
         .addOption((0, shared_1.appIdOption)().hideHelp())
-        .option("--since <time>", "开始时间")
-        .option("--until <time>", "截止时间")
-        .option("--trace-id <id>", "按 trace ID 过滤")
-        .option("--root-span <span-name>", "按入口节点关键词过滤")
-        .option("--user-id <user-id>", "按触发用户 ID 过滤")
-        .option("--limit <n>", "返回条数上限（1~100）", parseLimit, 50)
-        .option("--cursor <token>", "下一页游标")
-        .addHelpText("after", `${COMMON_TIME_HELP}
+        .option('--since <time>', '开始时间')
+        .option('--until <time>', '截止时间')
+        .option('--trace-id <id>', '按 trace ID 过滤')
+        .option('--root-span <span-name>', '按入口节点关键词过滤')
+        .option('--user-id <user-id>', '按触发用户 ID 过滤')
+        .option('--limit <n>', '返回条数上限（1~100）', parseLimit, 50)
+        .option('--cursor <token>', '下一页游标')
+        .addHelpText('after', `${COMMON_TIME_HELP}
 JSON 输出
   {"data": [...], "next_cursor": "...", "has_more": true|false}
 
@@ -114,8 +114,8 @@ JSON 输出
   $ miaoda observability trace list --root-span api-gateway --limit 20 --json
 `);
     listCmd.action((0, shared_1.withHelp)(listCmd, async (rawOpts) => {
-        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
-        (0, shared_1.rejectCliOverride)(listCmd, "appId");
+        (0, shared_1.validateTimeOptions)(rawOpts, 'since', 'until');
+        (0, shared_1.rejectCliOverride)(listCmd, 'appId');
         await (0, index_1.handleObservabilityTraceList)({
             appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             since: rawOpts.since,
@@ -128,12 +128,12 @@ JSON 输出
         });
     }));
     const getCmd = traceCmd
-        .command("get")
-        .description("查询指定链路的完整详情")
-        .argument("<trace-id>", "链路 ID")
+        .command('get')
+        .description('查询指定链路的完整详情')
+        .argument('<trace-id>', '链路 ID')
         .addOption((0, shared_1.appIdOption)().hideHelp())
-        .option("--with-log-severity-count", "返回每个 Span 各日志级别的数量", false)
-        .addHelpText("after", `
+        .option('--with-log-severity-count', '返回每个 Span 各日志级别的数量', false)
+        .addHelpText('after', `
 JSON 输出
   {"data": {"spans": [...], "isBreak": false}}
 
@@ -146,7 +146,7 @@ JSON 输出
     hint: 检查 trace-id 是否正确，或链路已超出保留时长
 `);
     getCmd.action((0, shared_1.withHelp)(getCmd, async (traceId, rawOpts) => {
-        (0, shared_1.rejectCliOverride)(getCmd, "appId");
+        (0, shared_1.rejectCliOverride)(getCmd, 'appId');
         await (0, index_1.handleObservabilityTraceGet)({
             traceId,
             appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
@@ -157,20 +157,20 @@ JSON 输出
 // ── metric ──
 function registerMetric(parent) {
     const cmd = parent
-        .command("metric")
-        .description("查询监控指标：requests / latency / cpu / memory")
-        .argument("<metric-name>", "指标名：requests | latency | cpu | memory")
+        .command('metric')
+        .description('查询监控指标：requests / latency / cpu / memory')
+        .argument('<metric-name>', '指标名：requests | latency | cpu | memory')
         .addOption((0, shared_1.appIdOption)().hideHelp())
-        .option("--page <path>", "按页面路径过滤（仅对 requests/latency 生效）")
-        .option("--api <path>", "按接口路径过滤（仅对 requests/latency 生效）")
-        .option("--series <name>", "过滤图表中的某条线：latency 取 p50/p99；requests 取 total/error；缺省返回所有相关线")
-        .option("--since <time>", "开始时间")
-        .option("--until <time>", "截止时间")
-        .addOption(new commander_1.Option("--down-sample <duration>", "降采样粒度（1m=1分钟 / 1h=1小时 / 1d=1天，大小写不敏感）")
-        .choices(["1m", "1h", "1d"])
-        .argParser((0, shared_1.caseInsensitiveChoice)(["1m", "1h", "1d"]))
-        .default("1m"))
-        .addHelpText("after", `${COMMON_TIME_HELP}
+        .option('--page <path>', '按页面路径过滤（仅对 requests/latency 生效）')
+        .option('--api <path>', '按接口路径过滤（仅对 requests/latency 生效）')
+        .option('--series <name>', '过滤图表中的某条线：latency 取 p50/p99；requests 取 total/error；缺省返回所有相关线')
+        .option('--since <time>', '开始时间')
+        .option('--until <time>', '截止时间')
+        .addOption(new commander_1.Option('--down-sample <duration>', '降采样粒度（1m=1分钟 / 1h=1小时 / 1d=1天，大小写不敏感）')
+        .choices(['1m', '1h', '1d'])
+        .argParser((0, shared_1.caseInsensitiveChoice)(['1m', '1h', '1d']))
+        .default('1m'))
+        .addHelpText('after', `${COMMON_TIME_HELP}
 JSON 输出
   {"data": [{"metricName": "...", "dimensions": {...}, "dataPoints": [...]}], "next_cursor": null, "has_more": false}
 
@@ -181,8 +181,8 @@ JSON 输出
   $ miaoda observability metric cpu --since 1d --down-sample 1d --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (metricName, rawOpts) => {
-        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
-        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        (0, shared_1.validateTimeOptions)(rawOpts, 'since', 'until');
+        (0, shared_1.rejectCliOverride)(cmd, 'appId');
         await (0, index_1.handleObservabilityMetric)({
             metricName,
             appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
@@ -198,16 +198,16 @@ JSON 输出
 // ── analytics ──
 function registerAnalytics(parent) {
     const cmd = parent
-        .command("analytics")
-        .description("查询运营指标：users（用户数）/ page-view（页面访问）")
-        .argument("<analytics-name>", "指标名：users | page-view")
+        .command('analytics')
+        .description('查询运营指标：users（用户数）/ page-view（页面访问）')
+        .argument('<analytics-name>', '指标名：users | page-view')
         .addOption((0, shared_1.appIdOption)().hideHelp())
-        .option("--page <path>", "按页面路径过滤（仅对 page-view 生效）")
-        .option("--series <name>", "过滤图表中的某条线：users 取 active/new/total（兼容 active-users/new-users/total-users）；page-view 取 all/desktop/mobile（兼容 all-view/desktop-view/mobile-view）")
-        .option("--since <time>", "开始时间")
-        .option("--until <time>", "截止时间")
-        .option("--granularity <duration>", "时间粒度：day | week | month", "day")
-        .addHelpText("after", `${COMMON_TIME_HELP}
+        .option('--page <path>', '按页面路径过滤（仅对 page-view 生效）')
+        .option('--series <name>', '过滤图表中的某条线：users 取 active/new/total（兼容 active-users/new-users/total-users）；page-view 取 all/desktop/mobile（兼容 all-view/desktop-view/mobile-view）')
+        .option('--since <time>', '开始时间')
+        .option('--until <time>', '截止时间')
+        .option('--granularity <duration>', '时间粒度：day | week | month', 'day')
+        .addHelpText('after', `${COMMON_TIME_HELP}
 JSON 输出
   {"data": [{"metricType": "...", "points": [{"timestampNs": "...", "value": ..., "dimensions": {...}}]}], "next_cursor": null, "has_more": false}
 
@@ -217,8 +217,8 @@ JSON 输出
   $ miaoda observability analytics page-view --granularity week --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (analyticsName, rawOpts) => {
-        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
-        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        (0, shared_1.validateTimeOptions)(rawOpts, 'since', 'until');
+        (0, shared_1.rejectCliOverride)(cmd, 'appId');
         await (0, index_1.handleObservabilityAnalytics)({
             analyticsName,
             appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),

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

@@ -4,13 +4,13 @@ exports.registerPluginCommands = registerPluginCommands;
 const index_1 = require("../../../cli/handlers/plugin/index");
 function registerPluginCommands(program) {
     const pluginCmd = program
-        .command("plugin")
-        .description("插件管理：安装/更新/移除插件包，查询 capability 实例")
-        .usage("<command> [flags]");
+        .command('plugin')
+        .description('插件管理：安装/更新/移除插件包，查询 capability 实例')
+        .usage('<command> [flags]');
     pluginCmd.action(() => {
         pluginCmd.outputHelp();
     });
-    pluginCmd.addHelpText("after", `
+    pluginCmd.addHelpText('after', `
 概念
   - 插件包 (plugin package)：.tgz 包，释放到 ./node_modules/<name>
   - actionPlugins：./package.json 里的字段，记录 { "@scope/name": "version" }，作为
@@ -26,10 +26,10 @@ function registerPluginCommands(program) {
   - remove / list / list-packages：纯本地 FS，不走网络
 `);
     pluginCmd
-        .command("install")
-        .description("拉取插件包并安装到当前应用项目")
-        .argument("<names...>", "插件名，格式 @scope/name 或 @scope/name@version；未带版本默认 latest")
-        .addHelpText("after", `
+        .command('install')
+        .description('拉取插件包并安装到当前应用项目')
+        .argument('<names...>', '插件名，格式 @scope/name 或 @scope/name@version；未带版本默认 latest')
+        .addHelpText('after', `
 行为
   - 拉取 .tgz 到本地缓存，解压到 ./node_modules/<name>
   - 在 ./package.json 的 actionPlugins 字段记录 <name>: <version>
@@ -62,10 +62,10 @@ JSON 输出
         await (0, index_1.handlePluginInstall)({ names });
     });
     pluginCmd
-        .command("update")
-        .description("把已安装插件升级到 latest 版本")
-        .argument("<names...>", "插件名，格式 @scope/name；带 @version 也只取 name 部分")
-        .addHelpText("after", `
+        .command('update')
+        .description('把已安装插件升级到 latest 版本')
+        .argument('<names...>', '插件名，格式 @scope/name；带 @version 也只取 name 部分')
+        .addHelpText('after', `
 行为
   - 仅对已在 actionPlugins 里的插件生效；未安装的插件返回 notInstalled
   - 拉取 latest 版本 .tgz，覆盖安装到 ./node_modules/<name>
@@ -97,10 +97,10 @@ JSON 输出
         await (0, index_1.handlePluginUpdate)({ names });
     });
     pluginCmd
-        .command("remove")
-        .description("从当前项目移除一个已安装的插件")
-        .argument("<name>", "插件名，格式 @scope/name")
-        .addHelpText("after", `
+        .command('remove')
+        .description('从当前项目移除一个已安装的插件')
+        .argument('<name>', '插件名，格式 @scope/name')
+        .addHelpText('after', `
 行为
   - 删除 ./node_modules/<name> 目录
   - 从 ./package.json 的 actionPlugins 字段移除对应条目
@@ -123,9 +123,9 @@ JSON 输出
         (0, index_1.handlePluginRemove)({ name });
     });
     pluginCmd
-        .command("init")
-        .description("按 package.json 的 actionPlugins 批量安装所有插件")
-        .addHelpText("after", `
+        .command('init')
+        .description('按 package.json 的 actionPlugins 批量安装所有插件')
+        .addHelpText('after', `
 行为
   - 读取 ./package.json 的 actionPlugins，对每个条目按固定版本安装
   - 已经是目标版本的跳过（幂等），用于 clone 项目后首次同步 / CI
@@ -156,11 +156,11 @@ JSON 输出
         await (0, index_1.handlePluginInit)();
     });
     pluginCmd
-        .command("list")
-        .description("列出当前项目的 capability 实例（./server/capabilities/*.json）")
-        .option("--summary", "不 hydrate（不充血），直接返回 capability 文件的原始 JSON")
-        .option("--id <id>", "只查询指定 id 的单个 capability")
-        .addHelpText("after", `
+        .command('list')
+        .description('列出当前项目的 capability 实例（./server/capabilities/*.json）')
+        .option('--summary', '不 hydrate（不充血），直接返回 capability 文件的原始 JSON')
+        .option('--id <id>', '只查询指定 id 的单个 capability')
+        .addHelpText('after', `
 行为
   - 扫描 ./server/capabilities/*.json（排除 capabilities.json）
   - 默认对每条 capability 做 hydrate：读取 ./node_modules/<pluginKey>/manifest.json，
@@ -190,9 +190,9 @@ JSON 输出
         await (0, index_1.handlePluginList)(opts);
     });
     pluginCmd
-        .command("list-packages")
-        .description("列出 package.json actionPlugins 里已声明的插件包")
-        .addHelpText("after", `
+        .command('list-packages')
+        .description('列出 package.json actionPlugins 里已声明的插件包')
+        .addHelpText('after', `
 行为
   - 读取 ./package.json 的 actionPlugins 字段
   - 只看声明，不校验 ./node_modules 下是否实际存在

package/dist/cli/commands/shared.js

@@ -16,10 +16,10 @@ const args_1 = require("../../utils/args");
 Object.defineProperty(exports, "failArgs", { enumerable: true, get: function () { return args_1.failArgs; } });
 /** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption()) */
 function appIdOption() {
-    return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
+    return new commander_1.Option('--app-id <id>', '指定目标应用').env('MIAODA_APP_ID');
 }
 function branchOption() {
-    return new commander_1.Option("--branch <branch>", "分支（优先级：--branch > 当前仓库 HEAD 分支；非 git 目录回退应用默认分支）").env("LOCAL_MOCK_MIAODA_DEPLOY_BRANCH");
+    return new commander_1.Option('--branch <branch>', '分支（优先级：--branch > 当前仓库 HEAD 分支；非 git 目录回退应用默认分支）').env('LOCAL_MOCK_MIAODA_DEPLOY_BRANCH');
 }
 /**
  * soft-required: Commander 类型上 optional，runtime 校验必填。
@@ -36,8 +36,8 @@ function softRequiredOption(name, desc) {
 function resolveAppId(opts) {
     const id = opts.appId ?? process.env.MIAODA_APP_ID ?? process.env.app_id;
     if (!id) {
-        throw new error_1.AppError("APP_ID_MISSING", "未指定应用", {
-            next_actions: ["设置 export MIAODA_APP_ID=<id>"],
+        throw new error_1.AppError('APP_ID_MISSING', '未指定应用', {
+            next_actions: ['设置 export MIAODA_APP_ID=<id>'],
         });
     }
     return id;
@@ -53,7 +53,7 @@ function withHelp(cmd, handler) {
             await handler(...args);
         }
         catch (err) {
-            if (err instanceof error_1.AppError && err.code === "ARGS_INVALID") {
+            if (err instanceof error_1.AppError && err.code === 'ARGS_INVALID') {
                 process.stderr.write(`Error: ${err.message}\n`);
                 cmd.outputHelp();
                 process.exitCode = 2;
@@ -81,7 +81,7 @@ function caseInsensitiveChoice(canonical) {
     return (raw) => {
         const hit = map.get(raw.toLowerCase());
         if (hit === undefined) {
-            throw new commander_1.InvalidArgumentError(`Allowed choices are ${canonical.join(", ")} (case-insensitive).`);
+            throw new commander_1.InvalidArgumentError(`Allowed choices are ${canonical.join(', ')} (case-insensitive).`);
         }
         return hit;
     };
@@ -98,8 +98,8 @@ function validateTimeOptions(opts, ...names) {
         const value = opts[name];
         if (value === undefined)
             continue;
-        if (typeof value !== "string") {
-            (0, args_1.failArgs)(`--${name.replace(/([A-Z])/g, "-$1").toLowerCase()} 必须是时间字符串`);
+        if (typeof value !== 'string') {
+            (0, args_1.failArgs)(`--${name.replace(/([A-Z])/g, '-$1').toLowerCase()} 必须是时间字符串`);
         }
         (0, time_1.parseTimeToMs)(value);
     }
@@ -118,8 +118,8 @@ function validateTimeOptions(opts, ...names) {
  */
 function rejectCliOverride(cmd, ...optNames) {
     for (const name of optNames) {
-        if (cmd.getOptionValueSource(name) === "cli") {
-            const flag = "--" + name.replace(/([A-Z])/g, "-$1").toLowerCase();
+        if (cmd.getOptionValueSource(name) === 'cli') {
+            const flag = '--' + name.replace(/([A-Z])/g, '-$1').toLowerCase();
             (0, args_1.failArgs)(`${flag} 由沙箱/本地配置注入，不允许显式传递`);
         }
     }

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

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

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

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAppInit = handleAppInit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const index_1 = require("../../../services/app/init/index");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+/** miaoda app init [--template <stack>] [--conf <json>] */
+async function handleAppInit(opts) {
+    await Promise.resolve();
+    const targetDir = opts.targetDir ?? process.cwd();
+    const metaPath = node_path_1.default.join(targetDir, '.spark', 'meta.json');
+    // 幂等：.spark/meta.json 是 init 流程最后才写的，存在即代表"已完整成功一次"。
+    // 用 package.json 判幂等会让 install 失败、CWD 留下半渲染状态的应用永远 init 不了。
+    if (node_fs_1.default.existsSync(metaPath)) {
+        if (!(0, output_1.isJsonMode)()) {
+            process.stdout.write(`Already initialized: ${metaPath}\n`);
+        }
+        (0, output_1.emit)({
+            data: {
+                initialized: false,
+                reason: 'already_initialized',
+                targetDir,
+            },
+        });
+        return;
+    }
+    const stack = opts.template;
+    if (!stack) {
+        throw new error_1.AppError('ARGS_INVALID', '缺少 --template <stack>', {
+            next_actions: [`可用 stack：${index_1.SUPPORTED_STACKS.join(', ')}`],
+        });
+    }
+    if (!index_1.SUPPORTED_STACKS.includes(stack)) {
+        throw new error_1.AppError('ARGS_INVALID', `不支持的 template: ${stack}`, {
+            next_actions: [`可用 stack：${index_1.SUPPORTED_STACKS.join(', ')}`],
+        });
+    }
+    const version = opts.conf?.version;
+    const projectName = node_path_1.default.basename(targetDir);
+    const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
+    const steeringResult = (0, index_1.syncSteering)({
+        stack,
+        targetDir,
+        version: opts.conf?.steeringVersion,
+    });
+    const installResult = (0, index_1.installDependencies)({
+        targetDir,
+        skip: opts.skipInstall,
+        quietStdout: (0, output_1.isJsonMode)(),
+    });
+    (0, index_1.writeSparkMeta)(targetDir, {
+        appId: opts.appId,
+        template: stack,
+        templatePackage: tplResult.packageName,
+        templateVersion: tplResult.version,
+        steeringVersion: steeringResult.version,
+        archType: tplResult.archType,
+        installSource: installResult.source,
+        installHash: installResult.hash,
+    });
+    if (!(0, output_1.isJsonMode)()) {
+        process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+    }
+    (0, output_1.emit)({
+        data: {
+            initialized: true,
+            appId: opts.appId,
+            template: stack,
+            templatePackage: tplResult.packageName,
+            templateVersion: tplResult.version,
+            steeringVersion: steeringResult.version,
+            archType: tplResult.archType,
+            syncedSkills: steeringResult.syncedSkills,
+            techSynced: steeringResult.techSynced,
+            installed: installResult.installed,
+            installSource: installResult.source,
+            installHash: installResult.hash,
+            cacheZip: installResult.cacheZip,
+        },
+    });
+}

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

@@ -41,7 +41,7 @@ const index_1 = require("../../../api/app/index");
 /** miaoda app update [--app-id <id>] [--name <n>] [--description <d>] */
 async function handleAppUpdate(opts) {
     if (opts.name === undefined && opts.description === undefined) {
-        (0, args_1.failArgs)("至少需要 --name 或 --description 中的一个");
+        (0, args_1.failArgs)('至少需要 --name 或 --description 中的一个');
     }
     const appID = opts.appId;
     await api.app.updateAppMeta({
@@ -53,7 +53,7 @@ async function handleAppUpdate(opts) {
     const resp = await api.app.getAppInfo(appID);
     const meta = resp.appInfo?.appMeta ?? {};
     if (!(0, output_1.isJsonMode)()) {
-        process.stdout.write("✓ App updated successfully\n");
+        process.stdout.write('✓ App updated successfully\n');
     }
     (0, output_1.emit)({ data: meta }, index_1.appMetaSchema);
 }

package/dist/cli/handlers/db/_destructive.js

@@ -0,0 +1,67 @@
+"use strict";
+// db 域内不可逆 / destructive 操作的统一确认门。
+//
+// 设计要点：
+//   1. --yes：放行（CI / 脚本显式确认场景）
+//   2. 非 TTY 且无 --yes：抛 DESTRUCTIVE_REQUIRES_CONFIRM，不要默认放行。
+//      非 TTY 通常是 CI / agent / 管道场景，无人能交互回答 y/N，必须靠 --yes 显式确认。
+//   3. TTY 且无 --yes：交互式 y/N（prompt 写 stderr，避免污染 --json 模式 stdout）
+//
+// 反例（已修复，见这次 commit）：把 !isJsonMode() 拿来做确认门 —— --json 只改输出
+// 格式，跟"用户已确认"不是同一语义。CI / agent 几乎总会带 --json 解析输出，等价于
+// 把不可逆操作的确认变成了空门，跟 file rm 的模型也不一致。
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmDestructive = confirmDestructive;
+exports.assertDestructiveAllowedInTty = assertDestructiveAllowedInTty;
+exports.askYesNo = askYesNo;
+const node_readline_1 = __importDefault(require("node:readline"));
+const render_1 = require("../../../utils/render");
+const error_1 = require("../../../utils/error");
+const DESTRUCTIVE_REQUIRES_CONFIRM_MSG = 'This operation is destructive. Rerun with --yes to confirm.';
+/**
+ * 完整的"yes/tty/交互"决策门。直接用于无需 fetch 预览的简单确认场景（如 migration init）。
+ *
+ * 返回值：
+ *   - true  → 已确认，可执行
+ *   - false → TTY 下用户输了 n，调用方应渲染 Aborted 并退出
+ *
+ * 异常：
+ *   - DESTRUCTIVE_REQUIRES_CONFIRM：非 TTY 且无 --yes
+ */
+async function confirmDestructive(prompt, yes) {
+    if (yes === true)
+        return true;
+    if (!(0, render_1.isStdoutTty)()) {
+        throw new error_1.AppError('DESTRUCTIVE_REQUIRES_CONFIRM', DESTRUCTIVE_REQUIRES_CONFIRM_MSG);
+    }
+    return askYesNo(prompt);
+}
+/**
+ * 给"需要在 confirm 之前先 fetch 预览"的场景（migration apply / recovery apply 可选优化）用：
+ * 在非 TTY 无 --yes 时提前抛错，避免无意义触发后端 dry-run RPC。
+ *
+ * 调用后 TTY 路径仍需自行调 askYesNo / confirmDestructive 完成交互。
+ */
+function assertDestructiveAllowedInTty(yes) {
+    if (yes === true)
+        return;
+    if (!(0, render_1.isStdoutTty)()) {
+        throw new error_1.AppError('DESTRUCTIVE_REQUIRES_CONFIRM', DESTRUCTIVE_REQUIRES_CONFIRM_MSG);
+    }
+}
+/**
+ * 交互式 y/N。输入读 stdin，prompt 写 stderr —— stderr 避免污染 --json 模式 stdout 的 envelope。
+ * 仅 'y'（忽略大小写）算确认；其余一律视为否决。
+ */
+async function askYesNo(prompt) {
+    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}

package/dist/cli/handlers/db/_env.js

@@ -0,0 +1,26 @@
+"use strict";
+// db 域内 --env 参数的 CLI vocab 校验。
+//
+// 用户视角的 vocab：
+//   - dev    → 多环境沙箱分支
+//   - online → 生产分支（向后端发请求时映射成 main，client.ts/api.ts 已处理）
+//   - main   → online 的别名，兼容历史脚本
+//
+// 配合 client.ts::buildUnknownEnvError，把 vocab 错（这里）跟 backend state 错
+// （client.ts 处理）统一成同一类 UNKNOWN_ENV_VALUE，避免用户在两种失败之间困惑。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnv = validateEnv;
+const client_1 = require("../../../api/db/client");
+const VOCAB = ['dev', 'main', 'online'];
+const VOCAB_SET = new Set(VOCAB);
+/**
+ * CLI vocab 校验。空值（未传 --env）放行，由后端按 workspace 默认 branch 处理。
+ * 不在 vocab 内 → 抛 UNKNOWN_ENV_VALUE，preAction hook 兜底，避免无意义触发 RPC。
+ */
+function validateEnv(env) {
+    if (env === undefined || env === '')
+        return;
+    if (VOCAB_SET.has(env))
+        return;
+    throw (0, client_1.buildUnknownEnvError)(env);
+}