@downcity/city 1.1.4 → 1.1.5

package/src/cli/shared/CliReporter.ts

@@ -0,0 +1,362 @@
+/**
+ * CLI Reporter：统一渲染 city 命令行输出。
+ *
+ * 关键点（中文）
+ * - 为 lifecycle 类命令提供稳定、统一、层级清晰的文本版式。
+ * - 将颜色、符号、对齐规则集中在这里，避免命令文件继续散落 `console.log` 模板串。
+ * - 保持纯函数输出，方便测试并保证非 TTY 场景仍可读。
+ */
+
+import chalk, { Chalk as ChalkConstructor } from "chalk";
+import type {
+  CliRenderOptions,
+  CliReportBlock,
+  CliReportFact,
+  CliReportList,
+  CliReportListItem,
+  CliReportTone,
+} from "./CliReporterTypes.js";
+
+const FACT_LABEL_MIN_WIDTH = 8;
+/**
+ * 解析终端可用宽度。
+ *
+ * 关键点（中文）
+ * - 读取 process.stdout.columns，窄终端（<80）用更紧凑的排版。
+ * - 最小 40 列，最大 120 列。
+ */
+function resolveCliWidth(): number {
+  const columns = process.stdout.columns || 80;
+  if (columns < 80) return 40;
+  if (columns < 100) return 60;
+  return Math.min(columns - 20, 100);
+}
+/** 当前命令已输出的 section 计数（管理 section 间空行）。 */
+let cliSectionPrinted = false;
+/** 上一个 section 是否紧凑（无 facts/note）。 */
+let cliPreviousSectionCompact = false;
+
+/**
+ * 全局 verbosity 级别。
+ * - "quiet"：仅输出 error 级别 block。
+ * - "normal"：输出全部内容（默认）。
+ * - "verbose"：输出更多细节（暂同 normal）。
+ */
+let cliVerbosity: "quiet" | "normal" | "verbose" = "normal";
+
+/**
+ * 设置全局 verbosity 级别。
+ *
+ * 关键点（中文）
+ * - 由 CLI 入口在 parse 前调用。
+ * - quiet 模式下 suppress 所有非 error 的 emitCliBlock/emitCliList。
+ */
+export function setCliVerbosity(level: "quiet" | "normal" | "verbose"): void {
+  cliVerbosity = level;
+}
+
+/**
+ * CLI 语气对应的视觉调色板。
+ */
+type CliTonePalette = {
+  /** 当前语气的标题颜色。 */
+  title: (text: string) => string;
+  /** 当前语气的状态颜色。 */
+  status: (text: string) => string;
+};
+
+/**
+ * 解析当前渲染应使用的 chalk 实例。
+ */
+function resolveChalk(options?: CliRenderOptions): typeof chalk {
+  if (options?.color === true) {
+    return new ChalkConstructor({ level: 1 });
+  }
+  if (options?.color === false) {
+    return new ChalkConstructor({ level: 0 });
+  }
+  return chalk;
+}
+
+/**
+ * 解析语气对应的完整视觉调色板。
+ */
+function resolveTonePalette(
+  tone: CliReportTone,
+  palette: typeof chalk,
+): CliTonePalette {
+  switch (tone) {
+    case "success":
+      return {
+        title: palette.bold,
+        status: palette.green,
+      };
+    case "warning":
+      return {
+        title: palette.bold,
+        status: palette.yellow,
+      };
+    case "error":
+      return {
+        title: palette.bold,
+        status: palette.red,
+      };
+    case "accent":
+      return {
+        title: palette.bold,
+        status: palette.cyan,
+      };
+    case "info":
+    default:
+      return {
+        title: palette.bold,
+        status: palette.blue,
+      };
+  }
+}
+
+/**
+ * 计算详情标签列宽。
+ */
+function resolveFactLabelWidth(facts: CliReportFact[]): number {
+  return facts.reduce((maxWidth, item) => {
+    return Math.max(
+      maxWidth,
+      normalizeFactLabel(String(item.label || "").trim()).length,
+    );
+  }, FACT_LABEL_MIN_WIDTH);
+}
+
+/**
+ * 规范化详情标签。
+ */
+function normalizeFactLabel(label: string): string {
+  return String(label || "").trim().toLowerCase();
+}
+
+/**
+ * 渲染详情键值对行。
+ */
+function formatFactLines(
+  facts: CliReportFact[],
+  indent: string,
+  options?: CliRenderOptions,
+): string[] {
+  const palette = resolveChalk(options);
+  const labelWidth = resolveFactLabelWidth(facts);
+  return facts.map((item) => {
+    const label = normalizeFactLabel(String(item.label || "")).padEnd(labelWidth, " ");
+    const value = formatFactValue(item.value, options);
+    return `${indent}${palette.dim(label)}  ${value}`;
+  });
+}
+
+/**
+ * 渲染标题行。
+ */
+function formatHeadingLine(params: {
+  tone: CliReportTone;
+  title: string;
+  summary?: string;
+  options?: CliRenderOptions;
+}): string {
+  const palette = resolveChalk(params.options);
+  const tonePalette = resolveTonePalette(params.tone, palette);
+  const renderedTitle = tonePalette.title(params.title);
+  if (!params.summary) {
+    return renderedTitle;
+  }
+  const plainSummary = String(params.summary || "").trim().toLowerCase();
+  const headlineWidth = resolveCliWidth();
+  const spacing = Math.max(
+    2,
+    headlineWidth - params.title.length - plainSummary.length,
+  );
+  return `${renderedTitle}${" ".repeat(spacing)}${tonePalette.status(plainSummary)}`;
+}
+
+/**
+ * 根据值内容做轻量语义高亮。
+ */
+function formatFactValue(
+  value: string,
+  options?: CliRenderOptions,
+): string {
+  const palette = resolveChalk(options);
+  const normalized = String(value || "");
+  if (/^https?:\/\//.test(normalized)) {
+    return palette.underline(normalized);
+  }
+  if (/^(started|stopped|ready|running)$/i.test(normalized)) {
+    return palette.green(normalized);
+  }
+  if (/^(already stopped|foreground)$/i.test(normalized)) {
+    return palette.blue(normalized);
+  }
+  if (/^(error|failed)$/i.test(normalized)) {
+    return palette.red(normalized);
+  }
+  return normalized;
+}
+
+/**
+ * 渲染单个信息区块（纯文本，不输出到 stdout）。
+ */
+export function formatCliBlock(
+  block: CliReportBlock,
+  options?: CliRenderOptions,
+): string {
+  const tone = block.tone || "info";
+  const palette = resolveChalk(options);
+  const lines = [
+    formatHeadingLine({
+      tone,
+      title: block.title,
+      summary: block.summary,
+      options,
+    }),
+  ];
+
+  if (Array.isArray(block.facts) && block.facts.length > 0) {
+    lines.push(...formatFactLines(block.facts, "  ", options));
+  }
+  if (block.note) {
+    const noteLabel = normalizeFactLabel("note").padEnd(
+      Math.max(FACT_LABEL_MIN_WIDTH, "note".length),
+      " ",
+    );
+    lines.push(`  ${palette.dim(noteLabel)}  ${block.note}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 渲染列表项（纯文本）。
+ */
+function formatCliListItem(
+  item: CliReportListItem,
+  options?: CliRenderOptions,
+): string[] {
+  const tone = item.tone || "info";
+  const lines = [
+    `  ${formatHeadingLine({
+      tone,
+      title: item.title,
+      options,
+    })}`,
+  ];
+  if (Array.isArray(item.facts) && item.facts.length > 0) {
+    lines.push(...formatFactLines(item.facts, "    ", options));
+  }
+  return lines;
+}
+
+/**
+ * 渲染列表分组（纯文本）。
+ */
+export function formatCliList(
+  list: CliReportList,
+  options?: CliRenderOptions,
+): string {
+  const tone = list.tone || "accent";
+  const lines = [
+    formatHeadingLine({
+      tone,
+      title: list.title,
+      summary: list.summary,
+      options,
+    }),
+  ];
+
+  for (const item of list.items) {
+    lines.push(...formatCliListItem(item, options));
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 渲染命令顶部 banner（纯文本）。
+ */
+export function formatCliHeader(
+  version: string,
+  options?: CliRenderOptions,
+): string {
+  const palette = resolveChalk(options);
+  return `${palette.bold("downcity")} ${palette.dim(`v${version}`)}`;
+}
+
+/**
+ * 重置当前命令的输出分组节奏。
+ *
+ * 关键点（中文）
+ * - 每次新的 CLI 命令开始输出前都应先重置。
+ * - 这样不同命令之间不会串联复用上一条命令的留白状态。
+ */
+export function resetCliSectionFlow(): void {
+  cliSectionPrinted = false;
+  cliPreviousSectionCompact = false;
+}
+
+/**
+ * 以统一节奏输出一个 section。
+ *
+ * 关键点（中文）
+ * - 第二个 section 起会自动插入一个空行，拉开模块层级。
+ * - 只负责打印节奏，不参与格式拼装。
+ */
+function emitCliSection(text: string, compact: boolean): void {
+  if (cliSectionPrinted && !(cliPreviousSectionCompact && compact)) {
+    console.log("");
+  }
+  console.log(text);
+  cliSectionPrinted = true;
+  cliPreviousSectionCompact = compact;
+}
+
+/**
+ * 判断 block 是否属于紧凑步骤行。
+ */
+function isCompactCliBlock(block: CliReportBlock): boolean {
+  return (!block.facts || block.facts.length === 0) && !block.note;
+}
+
+/**
+ * 判断 list 是否属于紧凑列表。
+ */
+function isCompactCliList(list: CliReportList): boolean {
+  return list.items.every((item) => !item.facts || item.facts.length === 0);
+}
+
+/**
+ * 输出 header section。
+ */
+export function emitCliHeader(
+  version: string,
+  options?: CliRenderOptions,
+): void {
+  emitCliSection(formatCliHeader(version, options), false);
+}
+
+/**
+ * 输出 block section。
+ */
+export function emitCliBlock(
+  block: CliReportBlock,
+  options?: CliRenderOptions,
+): void {
+  if (cliVerbosity === "quiet" && block.tone !== "error") return;
+  emitCliSection(formatCliBlock(block, options), isCompactCliBlock(block));
+}
+
+/**
+ * 输出 list section。
+ */
+export function emitCliList(
+  list: CliReportList,
+  options?: CliRenderOptions,
+): void {
+  if (cliVerbosity === "quiet") return;
+  emitCliSection(formatCliList(list, options), isCompactCliList(list));
+}

package/src/cli/shared/CliReporterTypes.ts

@@ -0,0 +1,167 @@
+/**
+ * CLI Reporter 类型定义。
+ *
+ * 关键点（中文）
+ * - 为 city CLI 的输出排版提供统一的结构化输入。
+ * - 所有命令层只描述“要表达什么”，具体排版交给 reporter 模块。
+ * - 类型与渲染器放在同一子域，避免输出协议继续漂移到集中类型目录。
+ */
+
+/**
+ * CLI 输出区块的语气类型。
+ */
+export type CliReportTone =
+  | "accent"
+  | "success"
+  | "info"
+  | "warning"
+  | "error";
+
+/**
+ * CLI 输出中的单条键值详情。
+ */
+export type CliReportFact = {
+  /**
+   * 当前详情项的标签文本。
+   *
+   * 说明（中文）
+   * - 会作为左侧对齐列展示，例如 `PID`、`Log`、`URL`。
+   * - 建议使用短标签，避免过长导致块体视觉松散。
+   */
+  label: string;
+  /**
+   * 当前详情项的值文本。
+   *
+   * 说明（中文）
+   * - 会原样展示在右侧内容列。
+   * - 调用方应提前完成路径、URL、数字等业务格式化。
+   */
+  value: string;
+};
+
+/**
+ * CLI 输出的基础信息区块。
+ */
+export type CliReportBlock = {
+  /**
+   * 当前区块的视觉语气。
+   *
+   * 说明（中文）
+   * - 控制前缀符号与颜色。
+   * - 未传时默认使用 `info` 语气。
+   */
+  tone?: CliReportTone;
+  /**
+   * 当前区块的主标题。
+   *
+   * 说明（中文）
+   * - 应直接表达当前步骤结果，例如 `Control plane started`。
+   * - 保持简短，避免与 facts 重复。
+   */
+  title: string;
+  /**
+   * 当前区块标题右侧的补充摘要。
+   *
+   * 说明（中文）
+   * - 常用于展示数量、动作阶段等短信息，例如 `1 item`、`restarting`。
+   * - 留空时不渲染摘要区域。
+   */
+  summary?: string;
+  /**
+   * 当前区块下方要展示的详情列表。
+   *
+   * 说明（中文）
+   * - 详情会按统一列宽对齐输出。
+   * - 留空或空数组时不渲染详情行。
+   */
+  facts?: CliReportFact[];
+  /**
+   * 当前区块的附注文本。
+   *
+   * 说明（中文）
+   * - 用于补充一句非结构化说明。
+   * - 会以弱化样式展示，避免抢主信息层级。
+   */
+  note?: string;
+};
+
+/**
+ * CLI 输出中的分组列表项。
+ */
+export type CliReportListItem = {
+  /**
+   * 当前列表项的视觉语气。
+   *
+   * 说明（中文）
+   * - 控制该项前缀符号与颜色。
+   * - 常见于成功/失败混合列表。
+   */
+  tone?: CliReportTone;
+  /**
+   * 当前列表项的主标题。
+   *
+   * 说明（中文）
+   * - 一般展示 agent 名称、服务名或项目名。
+   * - 尽量避免直接塞入大量详情信息。
+   */
+  title: string;
+  /**
+   * 当前列表项的详情列表。
+   *
+   * 说明（中文）
+   * - 与 block facts 语义一致，但缩进层级更深。
+   * - 用于展示 projectRoot、PID、log 等补充信息。
+   */
+  facts?: CliReportFact[];
+};
+
+/**
+ * CLI 输出中的列表分组。
+ */
+export type CliReportList = {
+  /**
+   * 当前列表分组的视觉语气。
+   *
+   * 说明（中文）
+   * - 控制分组标题前缀符号与颜色。
+   * - 未传时默认使用 `accent` 语气。
+   */
+  tone?: CliReportTone;
+  /**
+   * 当前列表分组的标题。
+   *
+   * 说明（中文）
+   * - 用于概括整个列表，例如 `Managed agents`。
+   */
+  title: string;
+  /**
+   * 当前列表分组的补充摘要。
+   *
+   * 说明（中文）
+   * - 常用于数量或动作状态，例如 `stopping · 2 items`。
+   */
+  summary?: string;
+  /**
+   * 当前分组下的列表项集合。
+   *
+   * 说明（中文）
+   * - 列表项按给定顺序输出。
+   * - 空数组时只展示标题，不展示子项。
+   */
+  items: CliReportListItem[];
+};
+
+/**
+ * CLI renderer 的可选渲染控制参数。
+ */
+export type CliRenderOptions = {
+  /**
+   * 是否强制启用 ANSI 颜色。
+   *
+   * 说明（中文）
+   * - `true` 时即使在非 TTY 下也会输出颜色。
+   * - `false` 时完全关闭颜色，便于测试断言。
+   * - 不传时沿用 chalk 默认探测行为。
+   */
+  color?: boolean;
+};