flu-cli 2.0.5 → 2.1.0

package/index.js

@@ -2,36 +2,37 @@
 
 /**
  * flu-cli v2.0
- * Flutter MVVM 脚手架工具
- * 
+ * Flutter 全流程效率工具链
+ *
  * 支持多种架构模板 and 代码生成功能
  */
 
 // ========== 加载 .env 文件 ==========
-import { readFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+import { dirname, resolve, isAbsolute } from 'path'
 
-function loadEnvFile () {
+function loadEnvFile() {
   try {
-    const envPath = resolve(process.cwd(), '.env');
+    const envPath = resolve(process.cwd(), '.env')
     if (existsSync(envPath)) {
-      const envContent = readFileSync(envPath, 'utf8');
-      const lines = envContent.split('\n');
+      const envContent = readFileSync(envPath, 'utf8')
+      const lines = envContent.split('\n')
+      const envDir = dirname(envPath)
 
       for (const line of lines) {
-        const trimmed = line.trim();
+        const trimmed = line.trim()
         // 跳过注释和空行
-        if (!trimmed || trimmed.startsWith('#')) continue;
+        if (!trimmed || trimmed.startsWith('#')) continue
 
-        const [key, ...valueParts] = trimmed.split('=');
-        const value = valueParts.join('=').trim();
+        const [key, ...valueParts] = trimmed.split('=')
+        const value = valueParts.join('=').trim()
 
         // 移除引号
-        const cleanValue = value.replace(/^["']|["']$/g, '');
+        const cleanValue = normalizeEnvPathValue(key, value.replace(/^["']|["']$/g, ''), envDir)
 
         // 只设置未定义的环境变量
         if (!process.env[key]) {
-          process.env[key] = cleanValue;
+          process.env[key] = cleanValue
         }
       }
     }
@@ -40,37 +41,58 @@ function loadEnvFile () {
   }
 }
 
-loadEnvFile();
+function normalizeEnvPathValue(key, value, baseDir) {
+  if (
+    (key === 'FLU_CLI_LOCAL_TEMPLATES_DIR' || key === 'FLU_CLI_BUNDLED_TEMPLATES_DIR') &&
+    value &&
+    !isAbsolute(value)
+  ) {
+    return resolve(baseDir, value)
+  }
+
+  return value
+}
 
-import { program } from 'commander';
-import chalk from 'chalk';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { newProjectWithClack } from './lib/commands/newClack.js';
-import { addComponent } from './lib/commands/add.js';
-import { listTemplates, showTemplateDetail } from './lib/commands/templates.js';
-import { updateTemplates, cleanCache } from './lib/commands/cache.js';
-import { t } from './lib/utils/i18n.js';
+loadEnvFile()
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import { fileURLToPath } from 'url'
+import { join } from 'path'
+import { newProjectWithClack } from './lib/commands/newClack.js'
+import { addComponent } from './lib/commands/add.js'
+import {
+  collectTemplateDetail,
+  collectTemplates,
+  listTemplates,
+  showTemplateDetail,
+} from './lib/commands/templates.js'
+import { updateTemplates, cleanCache } from './lib/commands/cache.js'
+import { t } from './lib/utils/i18n.js'
+import {
+  buildJsonEnvelope,
+  createNullLogger,
+  printJsonEnvelope,
+  runMuted,
+} from './lib/utils/json-output.js'
 
 // 获取 package.json
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const packageJson = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageJson = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'))
 
 // 设置版本和描述
-program
-  .version(packageJson.version)
-  .description(chalk.cyan(t('cli.description')));
+program.version(packageJson.version).description(chalk.cyan(t('cli.description')))
 
 // ========== 创建项目命令（V1 已废弃） ==========
 program
   .command('create')
   .description('⚠️  已废弃：请使用 flu new 命令')
   .action(() => {
-    console.log(chalk.yellow('\n⚠️  create 命令已在 V2 中废弃\n'));
-    console.log(chalk.cyan('请使用新命令：'));
-    console.log(chalk.green('  flu new <project-name>\n'));
-    process.exit(0);
-  });
+    console.log(chalk.yellow('\n⚠️  create 命令已废弃\n'))
+    console.log(chalk.cyan('请使用新命令：'))
+    console.log(chalk.green('  flu new <project-name>\n'))
+    process.exit(0)
+  })
 
 // ========== 新建项目命令（现代化交互式体验） ==========
 program
@@ -83,12 +105,46 @@ program
   .option('-p, --package <name>', '指定包名 (e.g., com.example.myapp)')
   .option('-a, --author <name>', '指定作者名称')
   .option('--no-cache', t('cmd.new.opt.no_cache'))
-  .option('--no-network', '不包含网络层（默认包含）')
+  .option('--network', '包含网络层')
+  .option('--no-network', '不包含网络层（lite/modular/clean 默认包含，native 默认不包含）')
+  .option('--auth', '启用 auth capability')
+  .option('--helpers <list>', '启用 helpers，逗号分隔: payment,webview,permission,imagePicker')
+  .option(
+    '--examples <list>',
+    '创建期示例，逗号分隔: networkGallery,webview,permission,image-picker,payment',
+  )
+  .option('--platforms <list>', '目标平台，逗号分隔: android,ios,web,harmony')
+  .option('--architecture-mode <mode>', '项目架构模式: mvvm,native')
+  .option('--composition-profile <profile>', '生成风格: base,base_mixins,pure,pure_mixins')
+  .option('--enable-mixin-options [value]', '是否准备 mixin 候选目录: true,false')
+  .option('--serialization <strategy>', '序列化策略: manual,json_serializable,freezed')
+  .option('--serialization-build-runner', '为 serialization 启用 build_runner')
+  .option('--flutter-sdk <mode>', 'Flutter SDK 模式: system,fvm,custom')
+  .option('--flutter-sdk-version <version>', 'FVM Flutter SDK 版本')
+  .option('--flutter-bin <path>', 'custom Flutter SDK 的 flutter 可执行文件路径')
   .option('--remote', t('cmd.new.opt.remote'))
-  .option('--flutter-template <type>', 'Flutter official template (app, module, package, plugin)', 'app')
-  .action((projectName, options) => {
-    newProjectWithClack(projectName, options);
-  });
+  .option(
+    '--json',
+    '以 JSON 输出创建结果（便于 IDE/脚本消费；需提供 project-name 与 --template）',
+    false,
+  )
+  .option(
+    '--flutter-template <type>',
+    'Flutter official template (app, module, package, plugin)',
+    'app',
+  )
+  .action(async (projectName, options) => {
+    if (options.json) {
+      const r = await runMuted(() => newProjectWithClack(projectName, options))
+      if (!r.ok) {
+        printJsonEnvelope(buildJsonEnvelope('new', false, [r.error], null))
+        process.exit(1)
+      }
+      printJsonEnvelope(buildJsonEnvelope('new', true, [], r.result))
+      return
+    }
+    await newProjectWithClack(projectName, options)
+  })
 
 // ========== 添加组件命令 ==========
 program
@@ -100,24 +156,51 @@ program
   .option('--stateless', t('cmd.add.opt.stateless'))
   .option('--list-page', t('cmd.add.opt.list_page'))
   .option('--no-vm', t('cmd.add.opt.no_vm'))
+  .option('--mixins <list>', '要附加的 mixin 名称，逗号分隔')
   .option('--json <file>', t('cmd.add.opt.json'))
+  .option('--out-json', '以 JSON 输出生成结果（不影响 --json <file> 作为输入参数）', false)
   .option('--list', t('cmd.add.opt.list'))
-  .action((type, name, options) => {
-    addComponent(type, name, options);
-  });
+  .action(async (type, name, options) => {
+    if (options.outJson) {
+      const r = await runMuted(() => addComponent(type, name, options))
+      const ok = r.ok && r.result?.ok === true
+      const diagnostics = r.ok ? (r.result?.diagnostics ?? []) : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('add', ok, diagnostics, r.ok ? r.result : null))
+      if (!ok) process.exit(1)
+      return
+    }
+    await addComponent(type, name, options)
+  })
 
 // ========== 模板管理命令 ==========
 program
   .command('templates [template-name]')
   .alias('t')
   .description(t('cmd.templates.desc'))
-  .action((templateName) => {
+  .option('--json', '以 JSON 输出模板信息（便于 IDE/脚本消费）', false)
+  .action((templateName, options) => {
+    if (options.json) {
+      if (templateName) {
+        const detail = collectTemplateDetail(templateName)
+        if (!detail) {
+          const diagnostics = [`模板 "${templateName}" 不存在`]
+          printJsonEnvelope(buildJsonEnvelope('templates.detail', false, diagnostics, null))
+          process.exit(1)
+        }
+        printJsonEnvelope(buildJsonEnvelope('templates.detail', true, [], detail))
+        return
+      }
+      const list = collectTemplates()
+      printJsonEnvelope(buildJsonEnvelope('templates.list', true, [], list))
+      return
+    }
+
     if (templateName) {
-      showTemplateDetail(templateName);
+      showTemplateDetail(templateName)
     } else {
-      listTemplates();
+      listTemplates()
     }
-  });
+  })
 
 // ========== 缓存管理命令 ==========
 program
@@ -126,62 +209,335 @@ program
   .alias('u')
   .description(t('cmd.update.desc'))
   .option('--force', t('cmd.update.opt.force'))
-  .action((templateName, options) => {
-    updateTemplates(templateName, options);
-  });
+  .option('--json', '以 JSON 输出更新结果（便于 IDE/脚本消费）', false)
+  .action(async (templateName, options) => {
+    if (options.json) {
+      const r = await runMuted(() => updateTemplates(templateName, options))
+      const diagnostics = r.ok ? [] : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('update-templates', r.ok, diagnostics, null))
+      if (!r.ok) process.exit(1)
+      return
+    }
+    await updateTemplates(templateName, options)
+  })
 
 program
   .command('cache <action>')
   .alias('c')
   .description(t('cmd.cache.desc'))
-  .action((action) => {
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action(async (action, options) => {
+    if (options.json) {
+      if (action !== 'clean') {
+        const diagnostics = [`未知的操作: ${action}`, '支持的操作: clean']
+        printJsonEnvelope(buildJsonEnvelope('cache', false, diagnostics, { action }))
+        process.exit(1)
+      }
+      const r = await runMuted(() => cleanCache())
+      const diagnostics = r.ok ? [] : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('cache.clean', r.ok, diagnostics, null))
+      if (!r.ok) process.exit(1)
+      return
+    }
     if (action === 'clean') {
-      cleanCache();
+      cleanCache()
     } else {
-      console.log(chalk.red(`未知的操作: ${action}`));
-      console.log(chalk.yellow('支持的操作: clean'));
+      console.log(chalk.red(`未知的操作: ${action}`))
+      console.log(chalk.yellow('支持的操作: clean'))
     }
-  });
+  })
 
 // ========== 应用资源管理 ==========
-import { configAssets } from './lib/commands/assets.js';
+import { configAssets } from './lib/commands/assets.js'
 
 program
   .command('assets')
   .alias('as')
   .description(t('cmd.assets.desc'))
   .option('-d, --dir <path>', t('cmd.new.opt.dir'), process.cwd())
-  .action((options) => {
-    configAssets(options);
-  });
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action(async (options) => {
+    if (options.json) {
+      const r = await runMuted(() => configAssets(options))
+      const diagnostics = r.ok ? [] : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('assets', r.ok, diagnostics, null))
+      if (!r.ok) process.exit(1)
+      return
+    }
+    await configAssets(options)
+  })
 
 // ========== 代码片段管理 ==========
-import { syncSnippets } from './lib/commands/snippets.js';
+import { syncSnippets } from './lib/commands/snippets.js'
 
 program
   .command('sync-snippets')
   .alias('sync')
   .description(t('cmd.sync.desc'))
-  .action(() => {
-    syncSnippets();
-  });
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action(async (options) => {
+    if (options.json) {
+      const r = await runMuted(() => syncSnippets())
+      const diagnostics = r.ok ? [] : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('sync-snippets', r.ok, diagnostics, null))
+      if (!r.ok) process.exit(1)
+      return
+    }
+    await syncSnippets()
+  })
+
+// ========== Blueprint 批量生成 ==========
+import { generateFromBlueprint, parseOpenApiToBlueprint } from 'flu-cli-core'
+import yaml from 'js-yaml'
+import http from 'http'
+import https from 'https'
+
+const bpProgram = program
+  .command('blueprint')
+  .alias('bp')
+  .description('🗺️  结构蓝图：生成骨架 / 从 OpenAPI 导入（可选）')
+
+// 子命令：flu blueprint gen（默认行为）
+bpProgram
+  .command('gen')
+  .description('从 flu-blueprint.yaml 批量生成页面、Service、Model')
+  .option('-d, --dir <path>', 'Flutter 项目根目录（含 .flu-cli.json）', process.cwd())
+  .option('-f, --file <path>', 'Blueprint 文件路径（默认 <dir>/flu-blueprint.yaml）')
+  .option('--json', '以 JSON 输出生成结果（便于 IDE/脚本消费）', false)
+  .action(async (options) => {
+    if (options.json) {
+      const nullLogger = createNullLogger()
+      const r = await runMuted(() => generateFromBlueprint(options.dir, options.file, nullLogger))
+      if (!r.ok) {
+        printJsonEnvelope(buildJsonEnvelope('blueprint.gen', false, [r.error], null))
+        process.exit(1)
+      }
+      const result = r.result
+      printJsonEnvelope(buildJsonEnvelope('blueprint.gen', result.ok, result.diagnostics, result))
+      if (!result.ok) process.exit(1)
+      return
+    }
 
-// ========== 模板管理命令 (New) ==========
-import { listAllTemplates, addTemplate, removeTemplate } from './lib/commands/template.js';
+    const result = await generateFromBlueprint(options.dir, options.file)
+    if (!result.ok) {
+      result.diagnostics.forEach((d) => console.error(chalk.red(d)))
+      process.exit(1)
+    }
+  })
+
+// 子命令：flu blueprint import <openapi>（可选增强）
+bpProgram
+  .command('import <openapi>')
+  .description(
+    '从 OpenAPI 3 文件/URL 导入并写入 flu-blueprint.yaml（不影响已有手写内容，默认合并）',
+  )
+  .option('-d, --dir <path>', 'Flutter 项目根目录', process.cwd())
+  .option('--replace', '替换整个 Blueprint（默认为合并）', false)
+  .option('--json', '以 JSON 输出导入结果（便于 IDE/脚本消费）', false)
+  .action(async (openapi, options) => {
+    const asJson = options.json === true
+    const report = {
+      ok: false,
+      openapi,
+      blueprintPath: `${options.dir}/flu-blueprint.yaml`,
+      mode: options.replace ? 'replace' : 'merge',
+      source: openapi.startsWith('http://') || openapi.startsWith('https://') ? 'url' : 'file',
+      diagnostics: [],
+      featureCount: 0,
+      endpointCount: 0,
+    }
 
-const templateCmd = program.command('template');
-templateCmd
-  .description(t('cmd.template.desc'))
-  .action(() => {
-    listAllTemplates();
-  });
+    // 读取 OpenAPI 内容（本地文件或 URL）
+    let raw = ''
+    try {
+      if (openapi.startsWith('http://') || openapi.startsWith('https://')) {
+        raw = await _fetchUrl(openapi)
+        if (!asJson) console.log(chalk.gray(`📡 已从 URL 获取 OpenAPI 文档`))
+      } else {
+        if (!existsSync(openapi)) {
+          report.diagnostics.push(`文件不存在：${openapi}`)
+          if (asJson) {
+            printJsonEnvelope(
+              buildJsonEnvelope('blueprint.import', false, report.diagnostics, report),
+            )
+          } else {
+            console.error(chalk.red(`❌ 文件不存在：${openapi}`))
+          }
+          process.exit(1)
+        }
+        raw = readFileSync(openapi, 'utf8')
+        if (!asJson) console.log(chalk.gray(`📄 已读取 OpenAPI 文件：${openapi}`))
+      }
+    } catch (e) {
+      report.diagnostics.push(`读取失败：${e.message}`)
+      if (asJson) {
+        printJsonEnvelope(buildJsonEnvelope('blueprint.import', false, report.diagnostics, report))
+      } else {
+        console.error(chalk.red(`❌ 读取失败：${e.message}`))
+      }
+      process.exit(1)
+    }
+
+    // 解析 OpenAPI → Blueprint
+    let imported
+    try {
+      imported = parseOpenApiToBlueprint(raw)
+    } catch (e) {
+      report.diagnostics.push(`OpenAPI 解析失败：${e.message}`)
+      if (asJson) {
+        printJsonEnvelope(buildJsonEnvelope('blueprint.import', false, report.diagnostics, report))
+      } else {
+        console.error(chalk.red(`❌ OpenAPI 解析失败：${e.message}`))
+      }
+      process.exit(1)
+    }
+
+    const bpPath = `${options.dir}/flu-blueprint.yaml`
+    let final = imported
+
+    // 合并模式：若已存在 blueprint，按 feature.name 合并
+    if (!options.replace && existsSync(bpPath)) {
+      try {
+        const existing = yaml.load(readFileSync(bpPath, 'utf8'))
+        final = _mergeBlueprints(existing, imported)
+        if (!asJson) console.log(chalk.gray('🔀 合并模式：已与现有 flu-blueprint.yaml 合并'))
+      } catch {
+        report.diagnostics.push('现有 blueprint 解析失败，将使用导入结果覆盖')
+        if (!asJson) console.log(chalk.yellow('⚠️  现有 blueprint 解析失败，将使用导入结果覆盖'))
+      }
+    } else if (options.replace) {
+      if (!asJson) console.log(chalk.gray('♻️  替换模式：将覆盖现有 flu-blueprint.yaml'))
+    }
+
+    writeFileSync(
+      bpPath,
+      yaml.dump(final, { indent: 2, lineWidth: 120, noCompatMode: true }),
+      'utf8',
+    )
+
+    const featureCount = final.features?.length ?? 0
+    const endpointCount = final.features?.reduce((s, f) => s + (f.endpoints?.length ?? 0), 0) ?? 0
+    report.ok = true
+    report.featureCount = featureCount
+    report.endpointCount = endpointCount
+    report.blueprintPath = bpPath
+
+    if (asJson) {
+      printJsonEnvelope(buildJsonEnvelope('blueprint.import', true, report.diagnostics, report))
+    } else {
+      console.log(chalk.green(`✅ flu-blueprint.yaml 已写入`))
+      console.log(chalk.gray(`   功能模块：${featureCount}，接口：${endpointCount}`))
+      console.log(chalk.gray(`   下一步：flu blueprint gen 或在 VSCode 「结构蓝图」面板预览并生成`))
+    }
+  })
+
+// 保持向后兼容：flu blueprint（不带子命令）= flu blueprint gen
+bpProgram.action(async () => {
+  console.log(chalk.yellow('提示：flu blueprint 已支持子命令，直接运行等同于 flu blueprint gen'))
+  console.log(chalk.gray('  flu blueprint gen      生成骨架'))
+  console.log(chalk.gray('  flu blueprint import   从 OpenAPI 导入'))
+  bpProgram.help()
+})
+
+/** 简单按 feature.name 合并两个 blueprint */
+function _mergeBlueprints(base, incoming) {
+  const featureMap = new Map((base.features ?? []).map((f) => [f.name, { ...f }]))
+  for (const f of incoming.features ?? []) {
+    if (featureMap.has(f.name)) {
+      const existing = featureMap.get(f.name)
+      // 合并 endpoints（按名称去重）
+      const existingNames = new Set((existing.endpoints ?? []).map((e) => e.name))
+      existing.endpoints = [
+        ...(existing.endpoints ?? []),
+        ...(f.endpoints ?? []).filter((e) => !existingNames.has(e.name)),
+      ]
+    } else {
+      featureMap.set(f.name, { ...f })
+    }
+  }
+  return { version: '1', features: Array.from(featureMap.values()) }
+}
+
+/** 从 URL 获取文本内容 */
+function _fetchUrl(url) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('https') ? https : http
+    client
+      .get(url, (res) => {
+        let data = ''
+        res.on('data', (chunk) => (data += chunk))
+        res.on('end', () => resolve(data))
+      })
+      .on('error', reject)
+  })
+}
+
+// ========== AI Skill 规则同步 ==========
+import { syncRules, syncRulesWithReport } from 'flu-cli-core'
+import { initAiBaseCli } from './lib/commands/init-ai-base.js'
+
+program
+  .command('sync-rules')
+  .alias('sr')
+  .description('🤖 从 .flu-cli.json 生成 AI Skill 规则文件（Cursor / Claude / AI_RULES.md）')
+  .option('-d, --dir <path>', '指定 Flutter 项目根目录', process.cwd())
+  .option('--json', '以 JSON 输出同步结果（便于 IDE/脚本消费）', false)
+  .action(async (options) => {
+    if (options.json) {
+      const nullLogger = createNullLogger()
+      const report = await syncRulesWithReport(options.dir, { logger: nullLogger })
+      const diagnostics = [...(report.diagnostics ?? [])]
+      if (report.error) diagnostics.push(report.error)
+      printJsonEnvelope(buildJsonEnvelope('sync-rules', report.ok, diagnostics, report))
+      if (!report.ok) process.exit(1)
+      return
+    }
+    const ok = await syncRules(options.dir)
+    if (!ok) process.exit(1)
+  })
+
+program
+  .command('init-ai-base')
+  .alias('iab')
+  .description('🤖 初始化 .flu-cli.json 并同步 AI 规则（空目录或已有项目均可）')
+  .option('-d, --dir <path>', '目标目录', process.cwd())
+  .option('-p, --project-id <id>', 'projectId（小写字母开头，英文/数字/短横线）')
+  .option('--json', '以 JSON 输出初始化结果（便于 IDE/脚本消费）', false)
+  .option(
+    '-s, --starter <name>',
+    '起步方案：minimal | lite | modular | clean | native | custom',
+    'minimal',
+  )
+  .option('--import <path>', 'starter=custom 时从该 JSON 文件导入；失败则兜底 minimal')
+  .action(async (options) => {
+    await initAiBaseCli(options)
+  })
+
+// ========== 模板管理命令 (New) ==========
+import {
+  listAllTemplates,
+  addTemplate,
+  removeTemplate,
+  collectAllTemplates,
+} from './lib/commands/template.js'
+
+const templateCmd = program.command('template')
+templateCmd.description(t('cmd.template.desc')).action(() => {
+  listAllTemplates()
+})
 
 templateCmd
   .command('list')
   .description(t('cmd.template.list.desc'))
-  .action(() => {
-    listAllTemplates();
-  });
+  .option('--json', '以 JSON 输出模板列表（便于 IDE/脚本消费）', false)
+  .action((options) => {
+    if (options.json) {
+      const data = collectAllTemplates()
+      printJsonEnvelope(buildJsonEnvelope('template.list', true, [], data))
+      return
+    }
+    listAllTemplates()
+  })
 
 templateCmd
   .command('add <id> <source>')
@@ -191,64 +547,160 @@ templateCmd
   .option('-b, --branch <branch>', t('cmd.template.add.opt.branch'))
   .option('-d, --description <text>', t('cmd.template.add.opt.desc'))
   .option('-f, --force', t('cmd.template.add.opt.force'))
-  .action((id, source, options) => {
-    addTemplate(id, source, options);
-  });
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action(async (id, source, options) => {
+    if (options.json) {
+      const r = await runMuted(() => addTemplate(id, source, options))
+      const diagnostics = r.ok ? [] : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('template.add', r.ok, diagnostics, { id, source }))
+      if (!r.ok) process.exit(1)
+      return
+    }
+    addTemplate(id, source, options)
+  })
 
 templateCmd
   .command('remove <id>')
   .description(t('cmd.template.remove.desc'))
-  .action((id) => {
-    removeTemplate(id);
-  });
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action(async (id, options) => {
+    if (options.json) {
+      const r = await runMuted(() => removeTemplate(id))
+      const diagnostics = r.ok ? [] : [r.error]
+      printJsonEnvelope(buildJsonEnvelope('template.remove', r.ok, diagnostics, { id }))
+      if (!r.ok) process.exit(1)
+      return
+    }
+    removeTemplate(id)
+  })
 
 // ========== 自动补全 ==========
-import { completion } from './lib/commands/completion.js';
+import { completion, getCompletionScript } from './lib/commands/completion.js'
 
 program
   .command('completion')
   .alias('comp')
   .description(t('cmd.completion.desc'))
-  .action(() => {
-    completion();
-  });
+  .option('--json', '以 JSON 输出补全脚本（便于 IDE/脚本消费）', false)
+  .action((options) => {
+    if (options.json) {
+      printJsonEnvelope(
+        buildJsonEnvelope('completion', true, [], { script: getCompletionScript() }),
+      )
+      return
+    }
+    completion()
+  })
 
 // ========== 配置管理命令 ==========
-import { initConfig, setConfig, getConfig } from './lib/commands/config.js';
-
-const configCmd = program.command('config');
-configCmd
-  .description(t('cmd.config.desc'))
-  .action(() => {
-    configCmd.help();
-  });
+import {
+  initConfig,
+  setConfig,
+  getConfig,
+  initConfigWithReport,
+  setConfigWithReport,
+  getConfigWithReport,
+  listGeneratorSelectableOptionsWithReport,
+} from './lib/commands/config.js'
+
+const configCmd = program.command('config')
+configCmd.description(t('cmd.config.desc')).action(() => {
+  configCmd.help()
+})
 
 configCmd
   .command('init')
   .description(t('cmd.config.init.desc'))
   .option('-d, --dir <path>', t('cmd.new.opt.dir'), process.cwd())
   .option('-f, --force', '覆盖已存在的配置文件')
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
   .action((options) => {
-    initConfig(options);
-  });
+    if (options.json) {
+      const report = initConfigWithReport(options)
+      printJsonEnvelope(buildJsonEnvelope('config.init', report.ok, report.diagnostics, report))
+      if (!report.ok) process.exit(1)
+      return
+    }
+    initConfig(options)
+  })
 
 configCmd
   .command('set <key> <value>')
   .description('Set global configuration (e.g., locale)')
-  .action((key, value) => {
-    setConfig(key, value);
-  });
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action((key, value, options) => {
+    if (options.json) {
+      const report = setConfigWithReport(key, value)
+      printJsonEnvelope(buildJsonEnvelope('config.set', report.ok, report.diagnostics, report))
+      if (!report.ok) process.exit(1)
+      return
+    }
+    setConfig(key, value)
+  })
 
 configCmd
   .command('get [key]')
   .description('Get global configuration')
-  .action((key) => {
-    getConfig(key);
-  });
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action((key, options) => {
+    if (options.json) {
+      const report = getConfigWithReport(key)
+      printJsonEnvelope(buildJsonEnvelope('config.get', report.ok, report.diagnostics, report))
+      if (!report.ok) process.exit(1)
+      return
+    }
+    getConfig(key)
+  })
+
+configCmd
+  .command('options')
+  .description('列出某类生成器的可选 Base/Mixin（给 Blueprint/IDE 下拉使用）')
+  .option('-d, --dir <path>', 'Flutter 项目根目录（含 .flu-cli.json）', process.cwd())
+  .option(
+    '-t, --target <type>',
+    '生成目标：page | viewModel | widget | model | component | service',
+    'page',
+  )
+  .option('--json', '以 JSON 输出执行结果（便于 IDE/脚本消费）', false)
+  .action((options) => {
+    if (options.json) {
+      const r = listGeneratorSelectableOptionsWithReport(options)
+      printJsonEnvelope(buildJsonEnvelope('config.options', r.ok, r.diagnostics, r.report))
+      if (!r.ok) process.exit(1)
+      return
+    }
+    const r = listGeneratorSelectableOptionsWithReport(options)
+    if (!r.ok) {
+      console.log(chalk.red(r.diagnostics.join('\n')))
+      process.exit(1)
+    }
+    console.log(JSON.stringify(r.report, null, 2))
+  })
+
+// ========== 上传发布命令 ==========
+import { uploadCommand } from './lib/commands/upload.js'
+
+program
+  .command('upload')
+  .description(t('cmd.upload.desc') || '打包并上传应用')
+  .option('--only-build', '仅执行构建，不上传')
+  .option('--only-upload', '仅执行上传 (需指定文件或自动查找)')
+  .option('--file <path>', '指定要上传的文件路径')
+  .option('--platform <items>', '指定发布平台 (逗号分隔, e.g. pgyer,huawei)')
+  .option('--desc <text>', '更新说明 (Changelog)')
+  .option('--json', '以 JSON 输出执行结果（目前仅返回错误信息）', false)
+  .action((options) => {
+    if (options.json) {
+      const diagnostics = ['upload 暂不支持 --json 输出（交互式流程），请先使用非 json 模式运行']
+      printJsonEnvelope(buildJsonEnvelope('upload', false, diagnostics, null))
+      process.exit(1)
+    }
+    uploadCommand(options)
+  })
 
-program.parse(process.argv);
+program.parse(process.argv)
 
 if (process.argv.length === 2) {
-  console.log(chalk.bold.cyan('\n🚀 欢迎使用 flu-cli v2.0\n'));
-  program.help({ error: false });
+  console.log(chalk.bold.cyan('\n🚀 欢迎使用 flu-cli v2.0\n'))
+  program.help({ error: false })
 }