Skip to content
Python
4.5 KB
Raw Blame
import {
  CAPABILITY_ALIASES,
  COMMANDS,
  type CommandDescriptor,
  type CommandOption,
} from "./command-catalog.js";
import { EXIT_CODES, EXIT_USAGE } from "./exit-codes.js";
import { CLI_VERSION, PRODUCT } from "./version.js";

const GLOBAL_OPTIONS: readonly CommandOption[] = [
  {
    flag: "--help, -h",
    summary: "显示帮助;可与 --json 组合输出机器可读目录。",
  },
  { flag: "--version, -V", summary: "显示 CLI 版本。" },
  {
    flag: "--json",
    summary:
      "以 JSON 输出到 stdout,供脚本与 Agent 消费;结果与失败都在 stdout,只有参数错误写 stderr。",
  },
  {
    flag: "--data-dir <path>",
    summary:
      "本次使用的 MemHub 数据目录(绝对路径);默认 ONE_MEMORY_DATA_DIR > 安装回执 > ~/.one-memory。",
  },
];

export function renderGeneralHelp(): string {
  return [
    `MemHub CLI ${CLI_VERSION}`,
    "",
    `Usage: ${PRODUCT} <command> [options]`,
    "",
    "Commands:",
    ...COMMANDS.map((command) => `  ${pad(command.name)}${command.summary}`),
    "",
    "Global options:",
    ...GLOBAL_OPTIONS.map((option) => `  ${pad(option.flag)}${option.summary}`),
    "",
    "Exit codes:",
    ...EXIT_CODES.map(
      (exit) => `  ${exit.code}  ${pad(exit.name, 17)}${exit.summary}`,
    ),
    "",
    "确认约定:只有不可逆操作(memories delete、models remove、delete-data、backup restore、graph-width --decision rebuild_with_new)需要 --yes;不加时只说明将要做什么,不做任何改动,exit 0。delete-data 与 backup restore 还要用 --confirm <path> 再写一遍目标路径。install/upgrade/uninstall/service-install/service-uninstall 不加 --yes 时只出计划。其它写命令直接执行。",
    "异步操作返回 ID,用对应命令查进度:sources receipt、models receipt、memories add-status、write status。",
    "目前仅支持 macOS 与 Linux 连接本机 Runtime。",
    "stdout 只输出数据,进度与诊断写入 stderr。",
    `运行 ${PRODUCT} help <command> 查看单个命令的参数。`,
    "",
  ].join("\n");
}

export function renderCommandHelp(command: CommandDescriptor): string {
  const lines = [`Usage: ${command.usage}`, ""];
  if (command.alternative_usage) {
    lines.push(command.alternative_usage, "");
  }
  lines.push(command.summary, "");
  if (command.options.length > 0) {
    lines.push(
      "Options:",
      ...command.options.map(
        (option) => `  ${pad(option.flag, 34)}${option.summary}`,
      ),
      "",
    );
  }
  lines.push(
    "Global options: --json、--data-dir <path>(见 memhub help)。",
    "",
    "Exit codes:",
    ...EXIT_CODES.filter((exit) => command.exit_codes.includes(exit.code)).map(
      (exit) => `  ${exit.code}  ${pad(exit.name, 17)}${exit.summary}`,
    ),
    "",
  );
  return lines.join("\n");
}

export function renderCatalogDocument(command?: CommandDescriptor): string {
  const identity = {
    schema_version: 1,
    product: PRODUCT,
    cli_version: CLI_VERSION,
  };
  return `${JSON.stringify(
    command
      ? { ...identity, command }
      : {
          ...identity,
          commands: COMMANDS,
          capability_aliases: CAPABILITY_ALIASES,
          exit_codes: EXIT_CODES,
        },
  )}\n`;
}

export function renderVersion(): string {
  return `${PRODUCT} ${CLI_VERSION}\n`;
}

export function renderVersionDocument(): string {
  return `${JSON.stringify({
    schema_version: 1,
    product: PRODUCT,
    cli_version: CLI_VERSION,
  })}\n`;
}

export function renderUsageError(
  command: CommandDescriptor | undefined,
  message: string,
): string {
  const nextStep = usageNextStep(command);
  const lines = [`${PRODUCT}: ${message}`];
  if (command) lines.push(`Usage: ${command.usage}`);
  lines.push(`下一步:${nextStep}`, "");
  return lines.join("\n");
}

export function renderUsageErrorDocument(
  command: CommandDescriptor | undefined,
  message: string,
): string {
  return `${JSON.stringify({
    schema_version: 1,
    product: PRODUCT,
    status: "usage_error",
    command: command?.name ?? null,
    usage: command?.usage ?? null,
    exit_code: EXIT_USAGE,
    message,
    next_step: usageNextStep(command),
  })}\n`;
}

function usageNextStep(command: CommandDescriptor | undefined): string {
  return command
    ? `运行 ${PRODUCT} help ${command.name} 查看该命令的参数。`
    : `运行 ${PRODUCT} help 查看可用命令。`;
}

function pad(value: string, width = 21): string {
  return value.length >= width ? `${value} ` : value.padEnd(width);
}