@newbeebox/newbeebox-app-engine-cli 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # nae —— NewBee App Engine CLI
 
-平台命令行客户端。**参数直达、JSON 输出**，既可人用，也便于 CodeAgent 编排调用。
+平台命令行客户端。**参数直达、默认人类可读**，加 `-o json` 即出 JSON，便于 CodeAgent 编排调用。
 
 > 📖 **完整文档（含 Agent 用法范例 / 调试技巧）**：<https://workshop.newbeebox.com/app_engine/documents/nae-cli/>
 > markdown 原文：<https://workshop.newbeebox.com/app_engine/documents/nae-cli/md/>
@@ -11,7 +11,6 @@
 
 ```bash
 npm i -g @newbeebox/newbeebox-app-engine-cli
-# 或在仓库内：npm install && npm link
 ```
 
 需要 Node ≥ 18（用到内置 `fetch`）。
@@ -44,13 +43,13 @@ nae apps
 
 ---
 
-## 输出契约（给 Agent）
+## 输出契约
 
-- **stdout**：只放数据，成功结果一律 JSON（默认美化，`-c/--compact` 输出单行）。日志命令直出文本行。
+- **stdout**：默认人类可读文本；加 `-o json` 出美化 JSON、`-c/--compact` 出紧凑单行 JSON。`logs`/`exec` 始终直出原始文本。
 - **stderr**：只放给人看的提示、进度、错误。
 - **退出码**：`0` 成功；`1` 业务错误；`2` 未登录/密钥失效；`3` 网络不可达。
 
-所以 Agent 可以安全地 `nae apps 2>/dev/null | jq '.[].AppID'`。
+所以 Agent 可以安全地 `nae apps -o json 2>/dev/null | jq '.[].AppID'`。
 
 ---
 
@@ -115,14 +114,13 @@ nae create --kind template --app-id myredis \
 | `nae logs <appid> [--pod P] [--container C] [--follow] [--tail N]` | 日志（缺省自动取首个 Pod） |
 | `nae exec <appid> -- <cmd...>` | 在容器内执行一条命令（非交互；输出与退出码透传） |
 
-### 模板 / 密钥
+### 模板
 
 | 命令 | 说明 |
 |------|------|
 | `nae templates` | 可用模板目录 |
-| `nae keys` | 我的 CLI 密钥列表 |
-| `nae keys:create --name <名> [--days 30\|60\|90\|0]` | 自建密钥（上限 5 条，`0`=永久） |
-| `nae keys:revoke <id>` | 吊销我的密钥 |
+
+> CLI 密钥的创建/查看/吊销仅在网页端「CLI 配置」页操作，命令行不提供。
 
 ---
 
@@ -130,6 +128,7 @@ nae create --kind template --app-id myredis \
 
 | 选项 | 说明 |
 |------|------|
+| `-o, --output <format>` | 输出格式：`text`（默认，人类可读）/ `json` |
+| `-c, --compact` | 紧凑 JSON（单行，隐含 `-o json`） |
 | `--base-url <url>` | 覆盖平台地址（亦可 `NAE_BASE_URL`） |
 | `--token <token>` | 覆盖访问密钥（亦可 `NAE_TOKEN`） |
-| `-c, --compact` | 紧凑 JSON（单行） |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@newbeebox/newbeebox-app-engine-cli",
-  "version": "1.0.0",
-  "description": "NewBee App Engine 命令行客户端（nae）——参数直达、JSON 输出，便于 CodeAgent 调用平台能力。",
+  "version": "1.0.2",
+  "description": "NewBee App Engine 命令行客户端（nae）——参数直达、默认人类可读（加 -o json 出 JSON），便于人用与 CodeAgent 调用平台能力。",
   "type": "module",
   "bin": {
     "nae": "src/index.js"

package/src/index.js

@@ -13,11 +13,12 @@ const program = new Command()
 
 program
   .name('nae')
-  .description('NewBee App Engine CLI —— 参数直达、JSON 输出，便于 CodeAgent 调用')
-  .version('1.0.0')
+  .description('NewBee App Engine CLI —— 默认人类可读，-o json 输出 JSON 供 CodeAgent 调用')
+  .version('1.0.2')
   .option('--base-url <url>', '覆盖平台地址（也可用环境变量 NAE_BASE_URL）')
   .option('--token <token>', '覆盖访问密钥（也可用环境变量 NAE_TOKEN）')
-  .option('-c, --compact', '紧凑 JSON 输出（单行）')
+  .option('-o, --output <format>', '输出格式：text（默认，人类可读）| json', 'text')
+  .option('-c, --compact', '紧凑 JSON 输出（单行，隐含 -o json）')
 
 // cfg 取合并了全局 flag 的配置。
 function cfg() {
@@ -28,9 +29,18 @@ function cfg() {
   return c
 }
 
-// emit 按 --compact 输出数据。
+// emit 按输出格式渲染数据：
+//   默认 text（人类可读）；-o json 出美化 JSON；-c/--compact 出紧凑 JSON（隐含 json）。
 function emit(value) {
-  out.data(value, { pretty: !program.opts().compact })
+  const o = program.opts()
+  const fmt = o.compact ? 'json' : o.output
+  if (fmt === 'json') {
+    out.data(value, { pretty: !o.compact })
+  } else if (fmt === 'text') {
+    out.human(value)
+  } else {
+    throw new Error(`未知输出格式：${fmt}（支持 text | json）`)
+  }
 }
 
 // run 包裹命令体，集中处理三类错误：
@@ -164,8 +174,31 @@ program
   .option('--storage <size>', '模板应用：持久卷大小，如 10Gi')
   .option('--replicas <n>', '副本数', (v) => parseInt(v, 10))
   .option('--env <json>', '环境变量 JSON，如 \'{"KEY":"val"}\'')
-  .option('--config <json>', '模板参数 JSON（密码/持久化模式等）')
+  .option(
+    '--config <json>',
+    "模板应用的服务特性参数 JSON。可用字段随模板而定，运行 'nae templates' 看每个模板的 ConfigSchema（key/类型/默认值/可选项）。redis: {\"password\",\"persistence\":\"rdb|aof|none\"}；milvus: {\"root_password\"}"
+  )
   .option('--owner <uid>', '管理员代他人创建时的归属用户 ID', (v) => parseInt(v, 10))
+  .addHelpText(
+    'after',
+    `
+示例：
+  # 普通应用：跟踪镜像 tag、监听 8080、限 0.5 核 512Mi、带环境变量
+  nae create --app-id myweb --tag latest --port 8080 --cpu 500m --mem 512Mi --env '{"FOO":"bar"}'
+
+  # 自带 basePath 的框架（Next.js Node server 等）：保留 /apps/<appid> 前缀
+  nae create --app-id mynext --tag latest --port 3000 --keep-path-prefix
+
+  # 模板应用 Redis：--config 取该模板的服务特性参数（见 nae templates）
+  nae create --kind template --app-id myredis --template redis --storage 2Gi \\
+    --config '{"password":"s3cret","persistence":"rdb"}'
+
+  # 模板应用 Milvus
+  nae create --kind template --app-id myvec --template milvus --storage 10Gi \\
+    --config '{"root_password":"s3cret"}'
+
+提示：先 'nae templates' 查模板 key 与各自 ConfigSchema 的字段；--config 留空则用各字段默认（密码类留空自动生成随机值，仅创建成功时返回一次）。`
+  )
   .action(
     run(async (opts) => {
       const body = {
@@ -304,31 +337,6 @@ program
   .description('列出可用模板')
   .action(run(async () => emit(await request(cfg(), 'GET', '/templates'))))
 
-// --- 自己的 CLI 密钥 ---
-
-program
-  .command('keys')
-  .description('列出我的 CLI 密钥')
-  .action(run(async () => emit(await request(cfg(), 'GET', '/me/api-keys'))))
-
-program
-  .command('keys:create')
-  .description('创建一枚 CLI 密钥（自建上限 5 条）')
-  .requiredOption('--name <name>', '备注名')
-  .option('--days <n>', '有效期天数：30/60/90，0=永久', (v) => parseInt(v, 10), 90)
-  .action(
-    run(async (opts) => {
-      emit(await request(cfg(), 'POST', '/me/api-keys', { body: { name: opts.name, valid_days: opts.days } }))
-    })
-  )
-
-program
-  .command('keys:revoke <id>')
-  .description('吊销一枚我的 CLI 密钥')
-  .action(
-    run(async (id) => {
-      emit(await request(cfg(), 'DELETE', `/me/api-keys/${parseInt(id, 10)}`))
-    })
-  )
+// CLI 密钥的创建/吊销/查看仅限网页端「CLI 配置」页，命令行不提供——见 nae login。
 
 program.parseAsync(process.argv)

package/src/output.js

@@ -1,14 +1,72 @@
-// 输出契约（给 CodeAgent 用的硬约定）：
-//   - stdout 只放「数据」：成功结果一律 JSON（默认美化），方便管道/解析。
+// 输出契约：
+//   - 默认输出「人类可读」文本到 stdout；加 `-o json`（或 `-c` 紧凑）才出 JSON，供 Agent 解析。
 //   - stderr 只放「给人看的」：提示、进度、错误。
 //   - 退出码：成功 0，失败非 0。
-// 这样 agent 可以 `nae apps 2>/dev/null | jq ...`，人也能从 stderr 读懂发生了什么。
+// 人读默认、机读按需——人直接看懂，Agent 用 `nae … -o json 2>/dev/null | jq …`。
 
 // data 把结果写到 stdout（JSON）。pretty=false 时输出紧凑单行。
 export function data(value, { pretty = true } = {}) {
   process.stdout.write(JSON.stringify(value, null, pretty ? 2 : 0) + '\n')
 }
 
+// human 把结果渲染成人类可读文本写到 stdout：
+//   - 标量 → 原样一行
+//   - 对象 → 「键: 值」多行；嵌套对象/数组缩进展开
+//   - 对象数组 → 逐条编号块（[1]/[2]…），宽数据也不会折行错乱
+// 需要稳定可解析格式请用 `-o json`。
+export function human(value) {
+  process.stdout.write(renderValue(value, '') + '\n')
+}
+
+function isScalar(v) {
+  return v === null || v === undefined || typeof v !== 'object'
+}
+
+function renderScalar(v) {
+  if (v === null || v === undefined) return ''
+  return String(v)
+}
+
+// renderValue 顶层分派。
+function renderValue(v, pad) {
+  if (isScalar(v)) return pad + renderScalar(v)
+  if (Array.isArray(v)) return v.length === 0 ? pad + '(空)' : renderArray(v, pad)
+  return renderObject(v, pad)
+}
+
+// renderObject 「键: 值」多行；嵌套对象/数组换行缩进。
+function renderObject(obj, pad) {
+  const keys = Object.keys(obj)
+  if (keys.length === 0) return pad + '(空)'
+  const lines = []
+  for (const k of keys) {
+    const v = obj[k]
+    if (isScalar(v)) {
+      lines.push(`${pad}${k}: ${renderScalar(v)}`)
+    } else if (Array.isArray(v) && v.length === 0) {
+      lines.push(`${pad}${k}: (空)`)
+    } else {
+      lines.push(`${pad}${k}:`)
+      lines.push(renderValue(v, pad + '  '))
+    }
+  }
+  return lines.join('\n')
+}
+
+// renderArray 标量数组每行一个；对象数组逐条编号块。
+function renderArray(arr, pad) {
+  const blocks = []
+  arr.forEach((item, i) => {
+    if (isScalar(item)) {
+      blocks.push(`${pad}- ${renderScalar(item)}`)
+    } else {
+      blocks.push(`${pad}[${i + 1}]`)
+      blocks.push(renderValue(item, pad + '  '))
+    }
+  })
+  return blocks.join('\n')
+}
+
 // line 直接写一行到 stdout（用于 logs 等本就是文本流的场景）。
 export function line(s) {
   process.stdout.write(s + '\n')