@newbeebox/newbeebox-app-engine-cli 1.0.0

package/README.md

@@ -0,0 +1,135 @@
+# nae —— NewBee App Engine CLI
+
+平台命令行客户端。**参数直达、JSON 输出**，既可人用，也便于 CodeAgent 编排调用。
+
+> 📖 **完整文档（含 Agent 用法范例 / 调试技巧）**：<https://workshop.newbeebox.com/app_engine/documents/nae-cli/>
+> markdown 原文：<https://workshop.newbeebox.com/app_engine/documents/nae-cli/md/>
+
+---
+
+## 安装
+
+```bash
+npm i -g @newbeebox/newbeebox-app-engine-cli
+# 或在仓库内：npm install && npm link
+```
+
+需要 Node ≥ 18（用到内置 `fetch`）。
+
+---
+
+## 登录
+
+CLI 用「个人访问令牌」鉴权。密钥明文只在创建时显示一次，请注意保存。
+
+```bash
+nae login
+```
+
+会引导你在浏览器打开网页端 **「CLI 配置」** 页创建一枚密钥，复制后粘贴回控制台即可。也可跳过交互直接传入：
+
+```bash
+nae login --token nae_xxxxxxxx
+```
+
+CI / Agent 场景免登录，直接用环境变量（优先级高于本地配置）：
+
+```bash
+export NAE_TOKEN=nae_xxxxxxxx
+export NAE_BASE_URL=https://workshop.newbeebox.com   # 可选，默认即此
+nae apps
+```
+
+配置存于 `~/.nae/config.json`。`nae logout` 清除本地密钥。
+
+---
+
+## 输出契约（给 Agent）
+
+- **stdout**：只放数据，成功结果一律 JSON（默认美化，`-c/--compact` 输出单行）。日志命令直出文本行。
+- **stderr**：只放给人看的提示、进度、错误。
+- **退出码**：`0` 成功；`1` 业务错误；`2` 未登录/密钥失效；`3` 网络不可达。
+
+所以 Agent 可以安全地 `nae apps 2>/dev/null | jq '.[].AppID'`。
+
+---
+
+## 命令
+
+### 身份 / 配额
+
+| 命令 | 说明 |
+|------|------|
+| `nae whoami` | 当前身份（uid/用户名/角色/命名空间） |
+| `nae quota` | 配额用量（CPU/内存/存储/应用数 的 已用/上限） |
+| `nae config` | 查看本地配置（密钥脱敏） |
+
+### 应用
+
+| 命令 | 说明 |
+|------|------|
+| `nae apps [--all]` | 列出应用（`--all` 仅管理员，看全平台） |
+| `nae app <appid>` | 应用详情/状态/设置 |
+| `nae children <appid>` | 子服务列表（如 Milvus 的 etcd/minio） |
+| `nae create --app-id <id> [...]` | 创建应用（见下） |
+| `nae delete <appid>` | 删除应用（模板级联清子服务/PVC/secret），幂等 |
+
+创建普通应用：
+
+```bash
+nae create --app-id myweb --tag latest --port 8080 \
+  --cpu 500m --mem 512Mi --env '{"FOO":"bar"}'
+# 自带 basePath 的框架（如 Next.js）加 --keep-path-prefix
+```
+
+创建模板应用：
+
+```bash
+nae create --kind template --app-id myredis \
+  --template redis --storage 2Gi --config '{"password":"..."}'
+```
+
+### 生命周期
+
+| 命令 | 说明 |
+|------|------|
+| `nae start <appid>` | 启动 |
+| `nae stop <appid>` | 停止（缩到 0） |
+| `nae restart <appid>` | 滚动重启 |
+| `nae scale <appid> <replicas>` | 扩缩容 |
+
+### 版本 / 回滚
+
+| 命令 | 说明 |
+|------|------|
+| `nae versions <appid>` | 镜像版本历史 |
+| `nae rollback <appid> [--seq N]` | 回滚（默认上一版） |
+
+### 运行态
+
+| 命令 | 说明 |
+|------|------|
+| `nae pods <appid>` | Pod 列表 |
+| `nae events <appid> [--limit N]` | 事件/时间线 |
+| `nae metrics <appid>` | 各 Pod 实时资源用量 |
+| `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>` | 吊销我的密钥 |
+
+---
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--base-url <url>` | 覆盖平台地址（亦可 `NAE_BASE_URL`） |
+| `--token <token>` | 覆盖访问密钥（亦可 `NAE_TOKEN`） |
+| `-c, --compact` | 紧凑 JSON（单行） |

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@newbeebox/newbeebox-app-engine-cli",
+  "version": "1.0.0",
+  "description": "NewBee App Engine 命令行客户端（nae）——参数直达、JSON 输出，便于 CodeAgent 调用平台能力。",
+  "type": "module",
+  "bin": {
+    "nae": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "newbee",
+    "app-engine",
+    "cli",
+    "paas",
+    "kubernetes",
+    "deploy",
+    "codeagent",
+    "nae"
+  ],
+  "homepage": "https://workshop.newbeebox.com/app_engine/documents/nae-cli/",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/config.js

@@ -0,0 +1,58 @@
+// 本地配置：~/.nae/config.json，仅两项——平台地址 baseUrl + 访问密钥 token。
+// 数据结构刻意最小：CLI 无状态机，每条命令读一次配置即可。
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
+
+const DEFAULT_BASE_URL = 'https://workshop.newbeebox.com'
+
+const CONFIG_DIR = join(homedir(), '.nae')
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json')
+
+// load 读配置；文件不存在/损坏一律回落到默认（不抛错，让首次使用顺畅）。
+// 环境变量优先级最高：NAE_BASE_URL / NAE_TOKEN 覆盖文件值（CI/agent 免登录直跑）。
+export function load() {
+  let cfg = { baseUrl: DEFAULT_BASE_URL, token: '' }
+  try {
+    const raw = readFileSync(CONFIG_FILE, 'utf8')
+    const parsed = JSON.parse(raw)
+    cfg = { ...cfg, ...parsed }
+  } catch {
+    // 无配置文件即首次使用，用默认值。
+  }
+  if (process.env.NAE_BASE_URL) cfg.baseUrl = process.env.NAE_BASE_URL
+  if (process.env.NAE_TOKEN) cfg.token = process.env.NAE_TOKEN
+  cfg.baseUrl = stripTrailingSlash(cfg.baseUrl || DEFAULT_BASE_URL)
+  return cfg
+}
+
+// save 持久化配置。目录不存在则建；文件权限收敛到 0600（含密钥，不给同机他人读）。
+export function save(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  const out = {
+    baseUrl: stripTrailingSlash(cfg.baseUrl || DEFAULT_BASE_URL),
+    token: cfg.token || '',
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(out, null, 2) + '\n', { mode: 0o600 })
+  try {
+    chmodSync(CONFIG_FILE, 0o600) // 已存在文件 writeFile 不改权限，显式收敛
+  } catch {
+    // Windows 不支持 POSIX 权限位，忽略。
+  }
+}
+
+// apiBase 拼出 /app_engine/api/v1 前缀（单域名路径路由）。
+export function apiBase(cfg) {
+  return `${stripTrailingSlash(cfg.baseUrl)}/app_engine/api/v1`
+}
+
+// cliPageUrl 网页端「CLI 配置」页地址，login 流程引导用户去这里建密钥。
+export function cliPageUrl(cfg) {
+  return `${stripTrailingSlash(cfg.baseUrl)}/app_engine/cli`
+}
+
+export const configPath = CONFIG_FILE
+
+function stripTrailingSlash(s) {
+  return String(s || '').replace(/\/+$/, '')
+}

package/src/http.js

@@ -0,0 +1,105 @@
+// HTTP 客户端：包 fetch，统一注入 Bearer 密钥、解封 {code,msg,data} 信封、归一错误。
+// 业务命令只管调 request() 拿 data，错误分类（网络/鉴权/业务）交给这里。
+import { apiBase } from './config.js'
+
+// ApiError 后端返回的业务错误（HTTP>=400 且带 {code,msg} 信封）。
+export class ApiError extends Error {
+  constructor(code, msg, status) {
+    super(msg || code)
+    this.name = 'ApiError'
+    this.code = code
+    this.status = status
+  }
+}
+
+// NetworkError 连不上平台（DNS/拒绝/超时等）。
+export class NetworkError extends Error {
+  constructor(msg) {
+    super(msg)
+    this.name = 'NetworkError'
+  }
+}
+
+// AuthError 未配置密钥，或密钥已失效/过期。携带可读引导。
+export class AuthError extends Error {
+  constructor(msg) {
+    super(msg)
+    this.name = 'AuthError'
+  }
+}
+
+// request 发一次请求并返回解封后的 data。
+//   cfg            : 配置（baseUrl/token）
+//   method, path   : 如 'GET', '/apps'
+//   opts.query     : 查询参数对象
+//   opts.body      : 请求体对象（自动 JSON）
+//   opts.token     : 覆盖 cfg.token（login 校验未落库的新密钥时用）
+//   opts.raw       : true 时返回原始 Response（流式日志用），不解封
+export async function request(cfg, method, path, opts = {}) {
+  const token = opts.token ?? cfg.token
+  if (!opts.allowNoToken && !token) {
+    throw new AuthError('未登录')
+  }
+
+  const url = new URL(apiBase(cfg) + path)
+  if (opts.query) {
+    for (const [k, v] of Object.entries(opts.query)) {
+      if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v))
+    }
+  }
+
+  const headers = {}
+  if (token) headers['Authorization'] = `Bearer ${token}`
+  let body
+  if (opts.body !== undefined) {
+    headers['Content-Type'] = 'application/json'
+    body = JSON.stringify(opts.body)
+  }
+
+  let resp
+  try {
+    resp = await fetch(url, { method, headers, body, signal: opts.signal })
+  } catch (e) {
+    throw new NetworkError(`无法连接到平台 ${cfg.baseUrl}（${e.message}）`)
+  }
+
+  if (opts.raw) {
+    if (!resp.ok) throw await toError(resp)
+    return resp
+  }
+
+  // 解封 {code,msg,data}。非 JSON（理论不该发生）按状态码兜底。
+  let payload
+  try {
+    payload = await resp.json()
+  } catch {
+    if (!resp.ok) throw new ApiError('internal', `HTTP ${resp.status}`, resp.status)
+    return null
+  }
+
+  if (!resp.ok || (payload && payload.code && payload.code !== 'ok')) {
+    throw classify(payload, resp.status)
+  }
+  return payload ? payload.data : null
+}
+
+async function toError(resp) {
+  let payload = null
+  try {
+    payload = await resp.json()
+  } catch {
+    /* 非 JSON 错误体 */
+  }
+  return classify(payload, resp.status)
+}
+
+// classify 把后端错误信封归一为对应错误类。鉴权类(forbidden + 401/403)升级为 AuthError，
+// 让上层据此提示「重新登录」。
+function classify(payload, status) {
+  const code = (payload && payload.code) || 'internal'
+  const msg = (payload && payload.msg) || `HTTP ${status}`
+  if (code === 'forbidden' || status === 401 || status === 403) {
+    return new AuthError(msg)
+  }
+  return new ApiError(code, msg, status)
+}

package/src/index.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// nae —— NewBee App Engine 命令行客户端。
+// 设计：薄壳。每条命令只做「取配置 → 调一个 HTTP 原语 → JSON 出 stdout」，
+// 鉴权/网络/业务错误集中在 run() 归类处理，命令体里不写 try/catch。
+import { Command } from 'commander'
+import { load, save, configPath } from './config.js'
+import { request, AuthError, NetworkError } from './http.js'
+import { runLogin } from './login.js'
+import { streamLogs } from './logs.js'
+import * as out from './output.js'
+
+const program = new Command()
+
+program
+  .name('nae')
+  .description('NewBee App Engine CLI —— 参数直达、JSON 输出，便于 CodeAgent 调用')
+  .version('1.0.0')
+  .option('--base-url <url>', '覆盖平台地址（也可用环境变量 NAE_BASE_URL）')
+  .option('--token <token>', '覆盖访问密钥（也可用环境变量 NAE_TOKEN）')
+  .option('-c, --compact', '紧凑 JSON 输出（单行）')
+
+// cfg 取合并了全局 flag 的配置。
+function cfg() {
+  const g = program.opts()
+  const c = load()
+  if (g.baseUrl) c.baseUrl = g.baseUrl.replace(/\/+$/, '')
+  if (g.token) c.token = g.token
+  return c
+}
+
+// emit 按 --compact 输出数据。
+function emit(value) {
+  out.data(value, { pretty: !program.opts().compact })
+}
+
+// run 包裹命令体，集中处理三类错误：
+//   AuthError    → 退出码 2，提示 nae login
+//   NetworkError → 退出码 3
+//   其它(ApiError/未知) → 退出码 1
+function run(fn) {
+  return (...args) => {
+    Promise.resolve(fn(...args)).catch((e) => {
+      if (e instanceof AuthError) {
+        out.info('未登录或密钥已失效。请先运行：nae login')
+        out.fail(e, 2)
+      } else if (e instanceof NetworkError) {
+        out.fail(e, 3)
+      } else {
+        out.fail(e, 1)
+      }
+    })
+  }
+}
+
+// 解析 JSON 字符串参数（--env / --config），失败给清晰报错。
+function parseJSONArg(label, s) {
+  if (s === undefined) return undefined
+  try {
+    return JSON.parse(s)
+  } catch {
+    throw new Error(`${label} 不是合法 JSON：${s}`)
+  }
+}
+
+// --- 认证 ---
+
+program
+  .command('login')
+  .description('登录：引导浏览器创建密钥并粘贴回来（或 --token 直接传入）')
+  .option('--token <token>', '直接使用已有密钥，跳过交互')
+  .action(
+    run(async (opts) => {
+      await runLogin(cfg(), opts.token)
+    })
+  )
+
+program
+  .command('logout')
+  .description('登出：清除本地保存的密钥')
+  .action(
+    run(async () => {
+      save({ ...load(), token: '' })
+      out.info('已登出，本地密钥已清除。')
+    })
+  )
+
+program
+  .command('whoami')
+  .description('显示当前身份（uid/用户名/角色/命名空间）')
+  .action(
+    run(async () => {
+      emit(await request(cfg(), 'GET', '/me'))
+    })
+  )
+
+program
+  .command('config')
+  .description('显示当前 CLI 配置（密钥脱敏）')
+  .action(
+    run(async () => {
+      const c = load()
+      emit({
+        configPath,
+        baseUrl: c.baseUrl,
+        token: c.token ? c.token.slice(0, 12) + '…' : '',
+        loggedIn: !!c.token,
+      })
+    })
+  )
+
+// --- 配额 ---
+
+program
+  .command('quota')
+  .description('查询当前用户配额用量（CPU/内存/存储/应用数 的 已用/上限）')
+  .action(
+    run(async () => {
+      emit(await request(cfg(), 'GET', '/me/quota'))
+    })
+  )
+
+// --- 应用 ---
+
+program
+  .command('apps')
+  .description('列出应用')
+  .option('--all', '管理员查看全平台应用')
+  .action(
+    run(async (opts) => {
+      emit(await request(cfg(), 'GET', '/apps', { query: opts.all ? { all: 'true' } : undefined }))
+    })
+  )
+
+program
+  .command('app <appid>')
+  .description('查看指定应用的详情/状态/设置')
+  .action(
+    run(async (appid) => {
+      emit(await request(cfg(), 'GET', `/apps/${appid}`))
+    })
+  )
+
+program
+  .command('children <appid>')
+  .description('查看应用的子服务列表（如 Milvus 的 etcd/minio）')
+  .action(
+    run(async (appid) => {
+      emit(await request(cfg(), 'GET', `/apps/${appid}/children`))
+    })
+  )
+
+program
+  .command('create')
+  .description('创建应用（普通应用或模板应用）')
+  .requiredOption('--app-id <id>', '应用 ID（地址中的 <appid>）')
+  .option('--kind <kind>', 'normal | template', 'normal')
+  .option('--tag <tag>', '普通应用：跟踪的镜像 tag')
+  .option('--port <n>', '普通应用：容器端口', (v) => parseInt(v, 10))
+  .option('--cpu <limit>', 'CPU 上限，如 1 / 500m')
+  .option('--mem <limit>', '内存上限，如 512Mi / 1Gi')
+  .option('--max-restarts <n>', '失败重启上限，0=不封顶', (v) => parseInt(v, 10))
+  .option('--keep-path-prefix', '不剥离 /apps/<appid> 前缀（自带 basePath 的框架用）')
+  .option('--template <key>', '模板应用：模板 key')
+  .option('--storage <size>', '模板应用：持久卷大小，如 10Gi')
+  .option('--replicas <n>', '副本数', (v) => parseInt(v, 10))
+  .option('--env <json>', '环境变量 JSON，如 \'{"KEY":"val"}\'')
+  .option('--config <json>', '模板参数 JSON（密码/持久化模式等）')
+  .option('--owner <uid>', '管理员代他人创建时的归属用户 ID', (v) => parseInt(v, 10))
+  .action(
+    run(async (opts) => {
+      const body = {
+        kind: opts.kind,
+        app_id: opts.appId,
+        tracked_tag: opts.tag,
+        container_port: opts.port,
+        cpu_limit: opts.cpu,
+        mem_limit: opts.mem,
+        max_restarts: opts.maxRestarts,
+        keep_path_prefix: opts.keepPathPrefix || undefined,
+        template_key: opts.template,
+        storage_size: opts.storage,
+        replicas: opts.replicas,
+        env: parseJSONArg('--env', opts.env),
+        config: parseJSONArg('--config', opts.config),
+        owner_id: opts.owner,
+      }
+      emit(await request(cfg(), 'POST', '/apps', { body }))
+    })
+  )
+
+program
+  .command('delete <appid>')
+  .description('删除应用（模板级联清子服务/PVC/secret），幂等')
+  .action(
+    run(async (appid) => {
+      emit(await request(cfg(), 'DELETE', `/apps/${appid}`))
+    })
+  )
+
+// --- 生命周期 ---
+
+program
+  .command('start <appid>')
+  .description('启动应用')
+  .action(run(async (id) => emit(await request(cfg(), 'POST', `/apps/${id}/start`))))
+
+program
+  .command('stop <appid>')
+  .description('停止应用（缩到 0）')
+  .action(run(async (id) => emit(await request(cfg(), 'POST', `/apps/${id}/stop`))))
+
+program
+  .command('restart <appid>')
+  .description('滚动重启应用')
+  .action(run(async (id) => emit(await request(cfg(), 'POST', `/apps/${id}/restart`))))
+
+program
+  .command('scale <appid> <replicas>')
+  .description('扩缩容到指定副本数')
+  .action(
+    run(async (id, replicas) => {
+      emit(await request(cfg(), 'POST', `/apps/${id}/scale`, { body: { replicas: parseInt(replicas, 10) } }))
+    })
+  )
+
+// --- 版本 / 回滚 ---
+
+program
+  .command('versions <appid>')
+  .description('镜像版本历史（Seq 倒序）')
+  .action(run(async (id) => emit(await request(cfg(), 'GET', `/apps/${id}/versions`))))
+
+program
+  .command('rollback <appid>')
+  .description('回滚（默认上一版，--seq 指定）')
+  .option('--seq <n>', '回滚到的版本 Seq', (v) => parseInt(v, 10))
+  .action(
+    run(async (id, opts) => {
+      emit(await request(cfg(), 'POST', `/apps/${id}/rollback`, { body: { seq: opts.seq ?? null } }))
+    })
+  )
+
+// --- 运行态：pods / events / metrics / logs ---
+
+program
+  .command('pods <appid>')
+  .description('Pod 列表')
+  .action(run(async (id) => emit(await request(cfg(), 'GET', `/apps/${id}/pods`))))
+
+program
+  .command('events <appid>')
+  .description('事件/时间线（倒序）')
+  .option('--limit <n>', '条数', (v) => parseInt(v, 10), 100)
+  .action(
+    run(async (id, opts) => {
+      emit(await request(cfg(), 'GET', `/apps/${id}/events`, { query: { limit: opts.limit } }))
+    })
+  )
+
+program
+  .command('metrics <appid>')
+  .description('各 Pod 实时资源用量')
+  .action(run(async (id) => emit(await request(cfg(), 'GET', `/apps/${id}/metrics`))))
+
+program
+  .command('logs <appid>')
+  .description('查看应用日志（默认取首个 Pod；--follow 持续跟随）')
+  .option('--pod <name>', '指定 Pod 名（缺省自动取首个）')
+  .option('--container <name>', '指定容器名')
+  .option('--follow', '持续跟随输出')
+  .option('--tail <n>', '末尾行数', (v) => parseInt(v, 10))
+  .action(
+    run(async (id, opts) => {
+      await streamLogs(cfg(), id, opts)
+    })
+  )
+
+// --- 在容器内执行命令（一次性非交互）---
+
+program
+  .command('exec <appid> [cmd...]')
+  .description('在应用容器内执行一条命令（非交互；命令写在 -- 之后）')
+  .option('--pod <name>', '指定 Pod（缺省取首个运行中的）')
+  .option('--container <name>', '指定容器')
+  .action(
+    run(async (appid, cmd, opts) => {
+      if (!cmd || cmd.length === 0) {
+        throw new Error('缺少命令。用法：nae exec <appid> -- <命令> [参数...]')
+      }
+      const res = await request(cfg(), 'POST', `/apps/${appid}/exec-run`, {
+        body: { command: cmd, pod: opts.pod, container: opts.container },
+      })
+      // 直出远端命令输出：stdout→stdout、stderr→stderr，进程退出码 = 远端退出码。
+      if (res.stdout) process.stdout.write(res.stdout)
+      if (res.stderr) process.stderr.write(res.stderr)
+      process.exit(res.exit_code || 0)
+    })
+  )
+
+// --- 模板目录 ---
+
+program
+  .command('templates')
+  .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)}`))
+    })
+  )
+
+program.parseAsync(process.argv)

package/src/login.js

@@ -0,0 +1,66 @@
+// 交互式登录：引导用户去网页「CLI 配置」页建密钥，粘贴回控制台，校验后落库。
+// 全程交互走 stderr（stdout 留给数据），保证 `nae login` 不污染管道。
+import { spawn } from 'node:child_process'
+import { createInterface } from 'node:readline/promises'
+import { stdin, stderr } from 'node:process'
+import { save, cliPageUrl } from './config.js'
+import { request, AuthError } from './http.js'
+import * as out from './output.js'
+
+// openBrowser 跨平台打开 URL；失败不致命（用户可手动复制）。
+function openBrowser(url) {
+  try {
+    if (process.platform === 'win32') {
+      // start 的首参是窗口标题，留空串避免把 URL 当标题。
+      spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref()
+    } else if (process.platform === 'darwin') {
+      spawn('open', [url], { stdio: 'ignore', detached: true }).unref()
+    } else {
+      spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref()
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+// runLogin 执行登录流程。tokenArg 非空则跳过交互直接用它（CI 友好）。
+export async function runLogin(cfg, tokenArg) {
+  let token = (tokenArg || '').trim()
+
+  if (!token) {
+    const pageUrl = cliPageUrl(cfg)
+    out.info('需要登录。请在浏览器打开「CLI 配置」页创建一枚访问密钥：')
+    out.info(`  ${pageUrl}`)
+    const opened = openBrowser(pageUrl)
+    out.info(opened ? '（已尝试为你打开浏览器）' : '（无法自动打开浏览器，请手动复制上面的地址）')
+    out.info('')
+
+    const rl = createInterface({ input: stdin, output: stderr })
+    try {
+      token = (await rl.question('创建后把密钥粘贴到这里，回车确认：')).trim()
+    } finally {
+      rl.close()
+    }
+  }
+
+  if (!token) {
+    throw new AuthError('未输入密钥')
+  }
+
+  // 用新密钥校验身份（命中 /me 即有效），通过后才落库。
+  out.info('正在校验密钥…')
+  let me
+  try {
+    me = await request(cfg, 'GET', '/me', { token })
+  } catch (e) {
+    if (e instanceof AuthError) {
+      throw new AuthError('密钥无效或已过期，请重新在网页创建')
+    }
+    throw e
+  }
+
+  save({ ...cfg, token })
+  out.info(`登录成功：${me.username}（${me.role === 'admin' ? '管理员' : '用户'}）`)
+  return me
+}

package/src/logs.js

@@ -0,0 +1,56 @@
+// 日志：服务端是 SSE（每帧 'data: <行>\n\n'）。这里用 raw 响应读流、逐行剥前缀打到 stdout。
+// 日志本就是文本流，不走 JSON 信封——stdout 直出行，便于 `nae logs x | grep`。
+import { request } from './http.js'
+import * as out from './output.js'
+
+// pickPod 未指定 --pod 时，取应用第一个 Pod 名。
+async function pickPod(cfg, appid) {
+  const pods = await request(cfg, 'GET', `/apps/${appid}/pods`)
+  if (!Array.isArray(pods) || pods.length === 0) {
+    throw new Error('该应用当前没有运行中的 Pod')
+  }
+  return pods[0]?.metadata?.name
+}
+
+// streamLogs 拉取并打印日志。follow=true 时持续跟随直到 Ctrl-C。
+export async function streamLogs(cfg, appid, opts) {
+  const pod = opts.pod || (await pickPod(cfg, appid))
+  out.info(`日志来源：应用 ${appid} / Pod ${pod}${opts.follow ? '（跟随中，Ctrl-C 退出）' : ''}`)
+
+  const controller = new AbortController()
+  // Ctrl-C 优雅收尾。
+  process.on('SIGINT', () => controller.abort())
+
+  const resp = await request(cfg, 'GET', `/apps/${appid}/logs`, {
+    raw: true,
+    signal: controller.signal,
+    query: {
+      pod,
+      container: opts.container,
+      follow: opts.follow ? 'true' : undefined,
+      tail: opts.tail,
+    },
+  })
+
+  const reader = resp.body.getReader()
+  const decoder = new TextDecoder()
+  let buf = ''
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buf += decoder.decode(value, { stream: true })
+      let idx
+      while ((idx = buf.indexOf('\n\n')) >= 0) {
+        const frame = buf.slice(0, idx)
+        buf = buf.slice(idx + 2)
+        for (const raw of frame.split('\n')) {
+          if (raw.startsWith('data: ')) out.line(raw.slice(6))
+          else if (raw.startsWith('data:')) out.line(raw.slice(5))
+        }
+      }
+    }
+  } catch (e) {
+    if (!controller.signal.aborted) throw e
+  }
+}

package/src/output.js

@@ -0,0 +1,28 @@
+// 输出契约（给 CodeAgent 用的硬约定）：
+//   - stdout 只放「数据」：成功结果一律 JSON（默认美化），方便管道/解析。
+//   - stderr 只放「给人看的」：提示、进度、错误。
+//   - 退出码：成功 0，失败非 0。
+// 这样 agent 可以 `nae apps 2>/dev/null | jq ...`，人也能从 stderr 读懂发生了什么。
+
+// data 把结果写到 stdout（JSON）。pretty=false 时输出紧凑单行。
+export function data(value, { pretty = true } = {}) {
+  process.stdout.write(JSON.stringify(value, null, pretty ? 2 : 0) + '\n')
+}
+
+// line 直接写一行到 stdout（用于 logs 等本就是文本流的场景）。
+export function line(s) {
+  process.stdout.write(s + '\n')
+}
+
+// info 给人看的提示到 stderr。
+export function info(s) {
+  process.stderr.write(s + '\n')
+}
+
+// fail 打印错误到 stderr 并以非 0 退出。err 可为 Error 或 {code,msg}。
+export function fail(err, code = 1) {
+  const msg =
+    (err && (err.msg || err.message)) || String(err) || '未知错误'
+  process.stderr.write(`错误：${msg}\n`)
+  process.exit(code)
+}