@tokenbuddy/tb-admin 1.0.30 → 1.0.32

package/src/provider.ts

@@ -0,0 +1,150 @@
+/**
+ * Step 12 (provider-agnostic seller management):
+ * 抽象 seller provider 接口, 让 tb-admin CLI + UI 不再 hardcode
+ * Fly.io 调用。
+ *
+ * 设计原则 (跟用户 ZCG 在 2026-06-11 凌晨讨论):
+ *  - 一个 `SellerProvider` 实现对应一种底层平台 (Fly.io / mock / ...).
+ *  - 5 个核心操作: listApps / statusApp / createApp / deployApp / removeApp.
+ *  - 所有方法都接受 dryRun, 都在 provider config 缺失必填字段时抛错.
+ *  - 所有方法都支持 `json: true` 输出, 方便 UI / 测试 / 自动化调用.
+ *  - Provider 通过 `ProviderRegistry` 注册, 默认 'fly' 实现是
+ *    `FlyProvider` (从 server-cmd.ts 拆出), 'mock' 是测试实现.
+ *  - 调用方 (CLI / UI / 其他) 都通过 `ProviderRegistry.get(name)` 取.
+ *  - `tb-admin seller <cmd>` CLI 子命令全部加 `--provider <name>`
+ *    (默认 'fly') + `--json` flag.
+ *
+ * 注意: Fly 字段 (`flyctl_path` / `default_region` / ...) 仍放在
+ * `SellerProviderConfig` 里, 不引入新的 provider 专用 config 字段
+ * (避免拆得过细). 未来加 K8s / 自建集群 provider 时, 把 `flyctl_path`
+ * 等字段移到 `FlyConfig` 子接口, 让 `SellerProviderConfig` 持有
+ * 通用字段 (default_region / default_image / volume_* 跨 provider 通用).
+ */
+
+import type { SellerProviderConfig } from "./config.js";
+
+/** Dry-run / json 通用选项, 所有方法都接受 */
+export interface ProviderCallOptions {
+  dryRun?: boolean;
+  /** 静默: 不打 [Fly.io] / [Mock] 之类的人类可读日志, 只输出 json */
+  silent?: boolean;
+}
+
+/** Provider 必须能列出所有它知道的应用, 跨 provider 字段对齐 */
+export interface SellerAppEntry {
+  /** Provider 内的应用 id (Fly 跟 K8s 各自定义) */
+  name: string;
+  /** 状态 (active / suspended / deployed / pending / unknown). 各 provider 各自定义枚举. */
+  status: string;
+  /** Provider 内部 id, 跨 provider 不必有意义. UI 用它跳转详情. */
+  providerId: string;
+  /** Region / zone / namespace. */
+  region?: string;
+  /** 上次部署时间 ISO 字符串. */
+  lastDeployAt?: string;
+  /** provider 特有的元数据 (machines count / image / 等) */
+  metadata?: Record<string, unknown>;
+}
+
+/** Provider 创建入参. 字段尽量 provider-agnostic; 私有字段放 `providerOptions` */
+export interface SellerCreateInput {
+  name: string;
+  region?: string;
+  image?: string;
+  operatorSecret: string;
+  initialConfigPath?: string;
+  volumeName?: string;
+  volumeSizeGb?: number;
+  volumeId?: string;
+  volumeSnapshotRetentionDays?: number;
+  dryRun?: boolean;
+  /** provider 私有扩展 (FlyConfig / K8sConfig / ...) */
+  providerOptions?: Record<string, unknown>;
+}
+
+/** Provider deploy 入参 */
+export interface SellerDeployInput {
+  app: string;
+  image?: string;
+  dryRun?: boolean;
+  providerOptions?: Record<string, unknown>;
+}
+
+/** Provider 通用 5 操作接口 */
+export interface SellerProvider {
+  /** provider 名 ('fly' / 'mock' / 'k8s' 等), 用于 `tb-admin --provider <name>` 选择 */
+  readonly name: string;
+
+  /** 检测 provider runtime 是否装好 (flyctl / kubectl / etc). CLI 启动时调用一次. */
+  isAvailable(): boolean;
+
+  /** List all apps this provider manages. */
+  listApps(options?: ProviderCallOptions): Promise<SellerAppEntry[]>;
+
+  /** Get one app's status (machine state / region / last deploy). */
+  statusApp(name: string, options?: ProviderCallOptions): Promise<SellerAppEntry>;
+
+  /** Create + initial deploy. `dryRun` 模式只输出计划. */
+  createApp(input: SellerCreateInput): Promise<{ ok: true; app: string; dryRun: boolean }>;
+
+  /** Update image on existing app. */
+  deployApp(input: SellerDeployInput): Promise<{ ok: true; app: string; machines: string[]; dryRun: boolean }>;
+
+  /** Destroy app. */
+  removeApp(name: string, options?: ProviderCallOptions): Promise<{ ok: true; app: string; dryRun: boolean }>;
+}
+
+/**
+ * Provider registry: CLI / UI / 测试都通过 `ProviderRegistry.get(name)`
+ * 拿 provider. 构造时塞一份 SellerProviderConfig, 跟现有
+ * `configManager.getSellerProvider(name)` 同源.
+ */
+export class ProviderRegistry {
+  private providers = new Map<string, SellerProvider>();
+
+  constructor(private configManager: { getSellerProvider(name?: string): SellerProviderConfig | undefined }) {}
+
+  /** 注册一个 provider. 测试场景用. */
+  register(provider: SellerProvider): void {
+    this.providers.set(provider.name, provider);
+  }
+
+  /** 取 provider. 默认 'fly'. 不存在抛错 (CLI 应该 fail fast). */
+  get(name: string = "fly"): SellerProvider {
+    const registered = this.providers.get(name);
+    if (registered) {
+      return registered;
+    }
+    // 还没注册 -> 现造一个 (FlyProvider / MockProvider 各自 lazy 构造)
+    const config = this.configManager.getSellerProvider(name);
+    if (!config) {
+      throw new Error(
+        `provider '${name}' is not configured. ` +
+        `Run \`tb-admin config set <profile>\` first, or add a [seller_providers.${name}] section.`
+      );
+    }
+    const instance = createDefaultProvider(name, config);
+    this.providers.set(name, instance);
+    return instance;
+  }
+
+  /** 列出所有已注册 provider 名. */
+  list(): string[] {
+    return Array.from(this.providers.keys());
+  }
+}
+
+/**
+ * 默认 provider 工厂. 'fly' -> FlyProvider.
+ * 任何未知 name 抛错. 通过 import 避免循环依赖, 所以放在文件底部.
+ */
+export function createDefaultProvider(name: string, config: SellerProviderConfig): SellerProvider {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { FlyProvider } = require("./server-cmd.js") as typeof import("./server-cmd.js");
+  if (name === "fly") {
+    // Step 14 之前 FlyProvider 暂不 implements SellerProvider (保留 1.0.31 行为 1:1).
+    // 这里通过 unknown 桥接; 真用时调用方应通过 SellerCommandRunner 而不是直接用 ProviderRegistry.
+    return new FlyProvider(config) as unknown as SellerProvider;
+  }
+  throw new Error(`unknown provider name: '${name}' (built-in: fly)`);
+}

package/src/seller.ts

@@ -0,0 +1,362 @@
+/**
+ * Step 12 v1.1 (增量): tb-admin seller 子命令 CLI 门面层.
+ *
+ * 1.0.31 现状:
+ *   - `tb-admin seller ls|create|deploy|remove` 4 个子命令
+ *   - 每个命令内部直接 `console.log(FlyProvider.<method>() 的 string 返回值)`
+ *   - 1.0.31 文本输出跟 flyctl 原始 stdout 一致 (人类可读表 / 状态文案)
+ *
+ * v1.1 增量:
+ *   1. 新增 `tb-admin seller status <app>` 第 5 子命令
+ *   2. 5 个子命令全部加 `--json` flag
+ *   3. `--json` 输出统一包装:
+ *      - ls/status: 直接拿 flyctl `--json` 解析后的 array / object
+ *      - create/deploy/remove: `{ ok, provider, action, app, dryRun, ... }`
+ *   4. 默认路径 1:1 保留 1.0.31 行为 (FlyProvider 不变, server-cmd.ts 不动)
+ *   5. UI 之后通过 spawn `tb-admin seller <cmd> --json` 取结构化数据
+ *
+ * 不改: FlyProvider 类 / server-cmd.ts / admin web / provider.ts.
+ * 不写 UI (Step 13).
+ */
+
+import { execSync, spawnSync } from "node:child_process";
+import { FlyProvider, type SellerCreateOptions } from "./server-cmd.js";
+import type { ConfigManager, SellerProviderConfig } from "./config.js";
+
+/** 单个 seller app 的 JSON 形态 (跟 flyctl apps list --json 对齐, 但只保留 UI 关心字段) */
+export interface SellerAppJson {
+  name: string;
+  status: string;
+  owner?: string;
+  region?: string;
+  version?: number;
+  latestDeployAt?: string;
+  /** raw flyctl 字段, 保留供未来扩展 */
+  raw: Record<string, unknown>;
+}
+
+/** ls --json 输出 */
+export interface SellerListResult {
+  ok: true;
+  provider: "fly";
+  action: "list";
+  count: number;
+  apps: SellerAppJson[];
+}
+
+/** status --json 输出 */
+export interface SellerStatusResult {
+  ok: true;
+  provider: "fly";
+  action: "status";
+  app: string;
+  status: Record<string, unknown>;
+}
+
+/** create / deploy / remove --json 输出 */
+export interface SellerActionResult<T extends "create" | "deploy" | "remove"> {
+  ok: true;
+  provider: "fly";
+  action: T;
+  app: string;
+  dryRun: boolean;
+  /** dry-run 模式下, 列出实际会跑的 flyctl 命令 */
+  commands?: string[];
+  /** 实际执行后, flyctl 输出摘录 (limited to stdout summary) */
+  summary?: string;
+  /** create/deploy 额外信息 */
+  machines?: string[];
+}
+
+export type SellerCommandResult =
+  | SellerListResult
+  | SellerStatusResult
+  | SellerActionResult<"create">
+  | SellerActionResult<"deploy">
+  | SellerActionResult<"remove">;
+
+export class FlyCliMissingError extends Error {
+  constructor(public readonly flyctl: string) {
+    super(`\`${flyctl}\` is not installed on your system PATH.`);
+    this.name = "FlyCliMissingError";
+  }
+}
+
+export class FlyCommandError extends Error {
+  constructor(
+    public readonly command: string,
+    public readonly exitCode: number,
+    public readonly stderr: string
+  ) {
+    super(`flyctl command failed (${exitCode}): ${command}\n${stderr.trim()}`);
+    this.name = "FlyCommandError";
+  }
+}
+
+/**
+ * 解析 flyctl apps list 文本输出 (人类可读表) -> 数组.
+ * 默认路径不变; --json 路径用 `parseFlyListJson` 走结构化路径.
+ */
+function parseFlyListText(text: string): SellerAppJson[] {
+  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  // 第一行 = 表头, 跳过; 后续行 = app 行
+  return lines.slice(1).map((line) => {
+    const cols = line.split("│").map((c) => c.trim());
+    return {
+      name: cols[0] || "",
+      status: cols[2] || "unknown",
+      owner: cols[1] || undefined,
+      latestDeployAt: cols[3] || undefined,
+      raw: { textLine: line }
+    };
+  });
+}
+
+function parseFlyListJson(jsonText: string): SellerAppJson[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonText || "[]");
+  } catch (err) {
+    throw new Error(`flyctl apps list --json returned invalid JSON: ${(err as Error).message}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`flyctl apps list --json did not return an array`);
+  }
+  return parsed.map((item) => {
+    if (!item || typeof item !== "object") {
+      return { name: String(item), status: "unknown", raw: { value: item } };
+    }
+    const obj = item as Record<string, unknown>;
+    const name = typeof obj.Name === "string" ? obj.Name : typeof obj.name === "string" ? obj.name : "";
+    const status = typeof obj.Status === "string" ? obj.Status : typeof obj.status === "string" ? obj.status : "unknown";
+    return {
+      name,
+      status,
+      owner: typeof obj.Owner === "string" ? obj.Owner : undefined,
+      region: typeof obj.Region === "string" ? obj.Region : undefined,
+      version: typeof obj.Version === "number" ? obj.Version : undefined,
+      latestDeployAt: typeof obj.Deployed === "boolean" && obj.Deployed ? new Date().toISOString() : undefined,
+      raw: obj
+    };
+  });
+}
+
+function parseFlyStatusJson(jsonText: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonText || "{}");
+  } catch (err) {
+    throw new Error(`flyctl status --json returned invalid JSON: ${(err as Error).message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`flyctl status --json did not return an object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+/**
+ * Low-level flyctl exec helper. Throws FlyCommandError on non-zero exit.
+ * Use this for --json path; default 1.0.31 path still goes through FlyProvider
+ * (which uses `stdio: "inherit"` for human consumption).
+ */
+function runFlyctlJson(
+  flyctl: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): unknown {
+  const result = spawnSync(flyctl, args, { encoding: "utf8", env });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new FlyCommandError(
+      `${flyctl} ${args.join(" ")}`,
+      result.status ?? -1,
+      result.stderr || result.stdout || ""
+    );
+  }
+  return result.stdout;
+}
+
+/**
+ * 顶层 seller 命令入口. 5 个 op 都走这里.
+ * - `json=false` (默认): 走 FlyProvider 现有方法, 返回人类可读 string, 调用方 console.log
+ * - `json=true`: 走结构化 flyctl --json + 包装, 返回 SellerCommandResult 对象
+ */
+export class SellerCommandRunner {
+  constructor(private configManager: ConfigManager) {}
+
+  private getProviderConfig(): SellerProviderConfig | undefined {
+    return this.configManager.getSellerProvider("fly");
+  }
+
+  private getProvider(): FlyProvider {
+    return new FlyProvider(this.getProviderConfig());
+  }
+
+  private getFlyctl(): string {
+    return this.getProviderConfig()?.flyctl_path || "flyctl";
+  }
+
+  // -- ls --
+
+  public ls(json: boolean): SellerListResult | string {
+    const provider = this.getProvider();
+    if (!json) {
+      return provider.listApps();
+    }
+    const flyctl = this.getFlyctl();
+    if (!providerCheck(flyctl)) {
+      throw new FlyCliMissingError(flyctl);
+    }
+    const env = flyEnv(this.getProviderConfig());
+    const stdout = runFlyctlJson(flyctl, ["apps", "list", "--json"], env) as string;
+    const apps = parseFlyListJson(stdout);
+    return { ok: true, provider: "fly", action: "list", count: apps.length, apps };
+  }
+
+  // -- status --
+
+  public status(appName: string, json: boolean): SellerStatusResult | string {
+    const provider = this.getProvider();
+    if (!json) {
+      return provider.statusApp(appName);
+    }
+    const flyctl = this.getFlyctl();
+    if (!providerCheck(flyctl)) {
+      throw new FlyCliMissingError(flyctl);
+    }
+    const resolvedName = appName.includes("-") ? appName : `tb-seller-${appName}`;
+    const env = flyEnv(this.getProviderConfig());
+    const stdout = runFlyctlJson(flyctl, ["status", "--app", resolvedName, "--json"], env) as string;
+    const status = parseFlyStatusJson(stdout);
+    return { ok: true, provider: "fly", action: "status", app: resolvedName, status };
+  }
+
+  // -- create --
+
+  public create(options: SellerCreateOptions, json: boolean): SellerActionResult<"create"> | string {
+    const provider = this.getProvider();
+    if (!json) {
+      return provider.createSeller(options);
+    }
+    // --json 路径: dry-run 模式直接列命令, 不实际调 flyctl
+    if (options.dryRun) {
+      return {
+        ok: true,
+        provider: "fly",
+        action: "create",
+        app: options.app || `tb-seller-${options.name}`,
+        dryRun: true,
+        commands: buildCreateCommands(options)
+      };
+    }
+    // 非 dry-run: 调 FlyProvider (它已经会跑 flyctl), 包装 stdout
+    const summary = provider.createSeller(options);
+    return {
+      ok: true,
+      provider: "fly",
+      action: "create",
+      app: options.app || `tb-seller-${options.name}`,
+      dryRun: false,
+      summary: String(summary)
+    };
+  }
+
+  // -- deploy --
+
+  public deploy(
+    args: { app: string; image?: string; dryRun?: boolean },
+    json: boolean
+  ): SellerActionResult<"deploy"> | string {
+    const provider = this.getProvider();
+    if (!json) {
+      return provider.deploySeller(args);
+    }
+    if (args.dryRun) {
+      return {
+        ok: true,
+        provider: "fly",
+        action: "deploy",
+        app: args.app,
+        dryRun: true,
+        commands: [`fly machine update <machine-id> --app ${args.app} --image ${args.image} --yes`]
+      };
+    }
+    const summary = provider.deploySeller(args);
+    return {
+      ok: true,
+      provider: "fly",
+      action: "deploy",
+      app: args.app,
+      dryRun: false,
+      summary: String(summary)
+    };
+  }
+
+  // -- remove --
+
+  public remove(appName: string, dryRun: boolean, json: boolean): SellerActionResult<"remove"> | string {
+    const provider = this.getProvider();
+    if (!json) {
+      return provider.removeSeller(appName, dryRun);
+    }
+    if (dryRun) {
+      return {
+        ok: true,
+        provider: "fly",
+        action: "remove",
+        app: appName,
+        dryRun: true,
+        commands: [`fly apps destroy ${appName} --yes`]
+      };
+    }
+    const summary = provider.removeSeller(appName, dryRun);
+    return {
+      ok: true,
+      provider: "fly",
+      action: "remove",
+      app: appName,
+      dryRun: false,
+      summary: String(summary)
+    };
+  }
+}
+
+// ===== helpers =====
+
+/** 跟 FlyProvider 私有 flyEnv 行为一致; 复用 provider config token */
+function flyEnv(config: SellerProviderConfig | undefined): NodeJS.ProcessEnv {
+  const configuredToken = config?.token;
+  const merged: NodeJS.ProcessEnv = { ...process.env };
+  if (configuredToken && !merged.FLY_API_TOKEN) {
+    merged.FLY_API_TOKEN = configuredToken;
+  }
+  return merged;
+}
+
+function providerCheck(flyctl: string): boolean {
+  try {
+    execSync(`which ${flyctl}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildCreateCommands(options: SellerCreateOptions): string[] {
+  const appName = options.app || `tb-seller-${options.name}`;
+  const region = options.region || "sin";
+  const lines: string[] = [];
+  if (options.flyConfig) {
+    lines.push(`fly apps create ${appName}`);
+  }
+  lines.push(`fly deploy --config ${options.flyConfig} --app ${appName} --region ${region}`);
+  if (options.image) {
+    lines.push(`fly machine update <machine-id> --app ${appName} --image ${options.image} --yes`);
+  }
+  return lines;
+}
+
+// re-exports 方便测试
+export { parseFlyListJson, parseFlyListText, parseFlyStatusJson };

package/src/ui-actions.ts

@@ -12,6 +12,12 @@ export interface UiActionResult {
   stdout: string;
   stderr: string;
   command: string[];
+  /**
+   * Step 13 (admin web -> CLI --json):
+   * 一些子命令 (`tb-admin seller <cmd> --json` 等) spawn 出来的 JSON.
+   * 1.0.32 行为 (无此字段) 不变; 新增字段不影响旧调用方.
+   */
+  json?: unknown;
 }
 
 export interface CreateSellerRequest {
@@ -172,7 +178,8 @@ export class UiActions {
         args.push("--dry-run");
       }
       report({ stepId: "create_deployment", status: "running", title: "Create Fly deployment", message: `Creating ${appName} in ${normalizedRequest.region}.` });
-      const result = await this.runAdmin(globalArgs(this.options, args), 10 * 60 * 1000);
+      // Step 13: 调 CLI --json 路径, admin web 拿到 result.json (结构化) + 1.0.32 result.stdout (兼容 UI)
+      const result = await this.runAdminJson(globalArgs(this.options, args), 10 * 60 * 1000);
       report({
         stepId: "create_deployment",
         status: result.ok ? "succeeded" : "failed",
@@ -254,20 +261,35 @@ export class UiActions {
   }
 
   public async setRegistryStatus(id: string, status: "active" | "draining" | "offline"): Promise<UiActionResult> {
+    // Step 14 (v1.1): tb-admin ui 现在走 vendor-scoped /platform/sellers/{id}/status.
+    // 老路径 `tb-admin bootstrap sellers status` (operator-level) 保留给 platform operator 显式调用.
+    // Vendor client 用当前 active profile 的 token, 跟 admin web 鉴权一致.
     const registry = await this.state.fetchRegistry();
     const target = registry.sellers.find((seller) => seller.id === id || seller.name === id || seller.app === id);
     if (!target) {
       throw new Error(`seller \`${id}\` not found in bootstrap registry`);
     }
-    return this.runAdmin(globalArgs(this.options, [
-      "bootstrap",
-      "sellers",
-      "status",
-      target.id,
-      status,
-      "--expect-version",
-      String(registry.version)
-    ]), 30000);
+    const { RegistryVendorClient } = await import("./vendor-client.js");
+    const profile = (this.state as unknown as { activeBootstrapProfile(): { profile?: { url?: string; token?: string } } }).activeBootstrapProfile();
+    const baseUrl = this.options.url || profile.profile?.url;
+    const token = this.options.token || profile.profile?.token;
+    if (!baseUrl || !token) {
+      throw new Error("No bootstrap profile found. Configure an admin profile or pass --url and --token.");
+    }
+    const client = new RegistryVendorClient(baseUrl, token);
+    const idempotencyKey = `tb-admin-ui-${target.id}-${status}-${registry.version}-${Date.now()}`;
+    const response = await client.setSellerStatus(target.id, status, {
+      expectedVersion: registry.version,
+      idempotencyKey
+    });
+    const newVersion = (response as { registry?: { version?: number } })?.registry?.version ?? registry.version + 1;
+    return {
+      ok: true,
+      stdout: `Set seller ${target.id} status=${status}: version=${newVersion} (vendor path)`,
+      stderr: "",
+      command: ["PUT", `/platform/sellers/${target.id}/status`, JSON.stringify({ status, expectedVersion: registry.version })],
+      json: response
+    };
   }
 
   public async deleteDeployment(id: string, confirm: boolean): Promise<UiActionResult> {
@@ -281,7 +303,8 @@ export class UiActions {
     if (!confirm) {
       args.push("--dry-run");
     }
-    return this.runAdmin(globalArgs(this.options, args), confirm ? 10 * 60 * 1000 : 30000);
+    // Step 13: 调 CLI --json 路径拿结构化 result.json (UI 暂仍按 1.0.32 用 stdout/stderr)
+    return this.runAdminJson(globalArgs(this.options, args), confirm ? 10 * 60 * 1000 : 30000);
   }
 
   private async withTempYaml<T>(document: unknown, callback: (filePath: string) => Promise<T>): Promise<T> {
@@ -313,6 +336,22 @@ export class UiActions {
     return runTbAdmin(args, timeoutMs);
   }
 
+  /**
+   * Step 13: 跟 `runAdmin` 一样 spawn tb-admin, 但 args 末尾追加 `--json` 并解析.
+   * 1.0.32 `commandRunner` 注入路径 (test mock): 解析成功就挂 json, 解析失败时 result.json
+   * 保持 undefined 但 ok 不变 (mock 拼的 stdout 经常不是 JSON, 强制失败会破坏所有老 test).
+   * 生产 spawn 路径走 runTbAdminJson, 那里解析失败才算 ok=false (真的 CLI 异常).
+   */
+  private runAdminJson(args: string[], timeoutMs: number): Promise<UiActionResult> {
+    if (this.commandRunner) {
+      return this.commandRunner([...args, "--json"], timeoutMs).then((result) => {
+        const parsed = parseJsonSafely(result.stdout);
+        return parsed === undefined ? { ...result } : { ...result, json: parsed };
+      });
+    }
+    return runTbAdminJson(args, timeoutMs);
+  }
+
   private async waitForSellerReady(appName: string, operatorSecret: string, report: UiActionProgressReporter): Promise<UiActionResult> {
     const maxAttempts = 18;
     const delayMs = 5000;
@@ -590,6 +629,45 @@ export function runTbAdmin(args: string[], timeoutMs: number): Promise<UiActionR
   });
 }
 
+/**
+ * Step 13 (admin web -> CLI --json):
+ * 跟 `runTbAdmin` 一样 spawn `tb-admin <args>`, **但 args 自动追加 `--json` flag**,
+ * 把 stdout 当 JSON 解析后挂在 result.json.
+ *
+ * 1.0.32 UI 调用方继续看 `result.stdout` / `result.ok` / `result.stderr`, 不破坏体验.
+ * UI 改造 (Step 14) 时改用 `result.json` 取结构化数据.
+ *
+ * 解析失败时 (CLI 输出不是 JSON, 比如老版本 CLI 没 --json), json 字段 = undefined,
+ * stdout 仍是原始字符串, ok=false (CLI exit 0 但 stdout 不可解析视为可恢复错).
+ */
+export function runTbAdminJson(args: string[], timeoutMs: number): Promise<UiActionResult> {
+  const jsonArgs = [...args, "--json"];
+  return runTbAdmin(jsonArgs, timeoutMs).then((result) => {
+    const parsed = parseJsonSafely(result.stdout);
+    if (parsed === undefined) {
+      return {
+        ...result,
+        ok: false,
+        stderr: result.stderr
+          ? `${result.stderr}\n[Step 13] failed to parse --json output`
+          : `[Step 13] failed to parse --json output`
+      };
+    }
+    return { ...result, json: parsed };
+  });
+}
+
+function parseJsonSafely(text: string): unknown | undefined {
+  if (!text || text.trim().length === 0) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
 async function defaultFetchJson(url: string, init?: RequestInit): Promise<unknown> {
   const response = await fetch(url, init);
   if (!response.ok) {

package/src/ui-server.ts

@@ -101,6 +101,15 @@ async function routeRequest(
     sendJson(res, 200, await state.bootstrapConfig());
     return;
   }
+  // Step 6 (registry redesign): legacy Bootstrap tab now surfaces
+  // vendor release requests from the wallet-bootstrap vendor API.
+  // TODO: wire this to call the active profile's wallet-bootstrap
+  // baseUrl with a vendor Bearer token. For now we return an empty
+  // list so the UI renders without a runtime error.
+  if (req.method === "GET" && parsed.pathname === "/api/vendor/release-requests") {
+    sendJson(res, 200, { releaseRequests: [] });
+    return;
+  }
   if (req.method === "GET" && parsed.pathname === "/api/sellers") {
     sendJson(res, 200, await state.sellers());
     return;