backtrace-console 0.0.1

package/lib/backtrace/options.js

@@ -0,0 +1,278 @@
+const path = require("node:path");
+const {
+  DEFAULT_QUERY_URL,
+  DEFAULT_BACKTRACE_PROJECT,
+  DEFAULT_BACKTRACE_FORMAT,
+  DEFAULT_WORKDIR,
+  DEFAULT_PROXY,
+  DEFAULT_SELECT,
+  DEFAULT_LIMIT,
+  DEFAULT_DOWNLOAD_CONCURRENCY,
+  DEFAULT_RETRIES,
+  DEFAULT_STORAGE_DIR,
+} = require("./constants");
+const { nowRange, formatBatchName } = require("./utils");
+
+function normalizeBacktraceQueryUrl(value) {
+  const rawValue = String(value || "").trim();
+  const fallbackUrl = new URL(DEFAULT_QUERY_URL);
+  const url = rawValue ? new URL(rawValue) : new URL(DEFAULT_QUERY_URL);
+  if (!url.pathname || url.pathname === "/") {
+    url.pathname = "/api/query";
+  }
+  if (!url.searchParams.get("project")) {
+    url.searchParams.set("project", process.env.BACKTRACE_PROJECT || DEFAULT_BACKTRACE_PROJECT);
+  }
+  if (!url.searchParams.get("format")) {
+    url.searchParams.set("format", process.env.BACKTRACE_FORMAT || DEFAULT_BACKTRACE_FORMAT);
+  }
+  if (!url.searchParams.get("token") && fallbackUrl.searchParams.get("token")) {
+    url.searchParams.set("token", fallbackUrl.searchParams.get("token"));
+  }
+  return url.toString();
+}
+
+function normalizeOptionalInteger(value, fallback) {
+  if (value === undefined || value === null || value === "") {
+    return fallback;
+  }
+  return Number(value);
+}
+
+// 顶层工具只暴露固定命令集合，便于尽早做参数校验。
+const SUPPORTED_COMMANDS = ["list", "fingerprint", "collect-all", "summarize-fingerprint-errors"];
+
+// 输出旧入口 codex_demo.js 和库调用共用的帮助信息。
+function printUsage() {
+  console.log(
+    [
+      "Usage:",
+      "  backtrace <command> [options]",
+      "",
+      "Commands:",
+      "  list                          list local fingerprint directories and meta information",
+      "  fingerprint                   query all grouped fingerprints and print them",
+      "  collect-all                   download all objects only, do not generate reports",
+      "  summarize-fingerprint-errors  summarize and deduplicate error lines for one local fingerprint directory",
+      "  fix-plan                      generate a repair plan from the smallest AboveLand.LOG under one fingerprint",
+      "",
+      "Environment:",
+      "  BACKTRACE_USERNAME     required Backtrace console login username",
+      "  BACKTRACE_PASSWORD     required Backtrace console login password",
+      `  BACKTRACE_PROJECT      default: ${DEFAULT_BACKTRACE_PROJECT}`,
+      `  BACKTRACE_FORMAT       default: ${DEFAULT_BACKTRACE_FORMAT}`,
+      "",
+      "Options:",
+      `  --query-url <url>      default base url: ${DEFAULT_QUERY_URL}`,
+      `  --workdir <dir>        default: ${DEFAULT_WORKDIR}`,
+      "  --fingerprint <value[,value2,...]>  optional query filter; collect supports multiple values",
+      "  --from <unixTs>        default: 1",
+      "  --to <unixTs>          default: now",
+      `  --limit <n>            default: ${DEFAULT_LIMIT}`,
+      "  --offset <n>           default: 0",
+      `  --select <a,b,c>       default: ${DEFAULT_SELECT.join(",")}`,
+      `  --proxy <url>          default: ${DEFAULT_PROXY}`,
+      `  --retries <n>          default: ${DEFAULT_RETRIES} (0 means infinite retry)`,
+      `  --download-concurrency <n> default: ${DEFAULT_DOWNLOAD_CONCURRENCY}`,
+      "  --storage-dir <dir>    default: ./fingerprints",
+      "  --report-dir <dir>     deprecated alias of --storage-dir",
+      "  --logs-dir <dir>       deprecated alias of --storage-dir",
+      "  --help                 show this message",
+    ].join("\n"),
+  );
+}
+
+// 对标准化选项做一次集中校验，
+// 后续流程就可以默认命令前置条件和数值范围都已成立。
+function validateOptions(options) {
+  if (!SUPPORTED_COMMANDS.includes(options.command)) {
+    throw new Error(`Command must be one of: ${SUPPORTED_COMMANDS.join(", ")}`);
+  }
+  if (options.command === "summarize-fingerprint-errors" && !options.fingerprint) {
+    throw new Error("--fingerprint is required for summarize-fingerprint-errors");
+  }
+  if (!["list", "summarize-fingerprint-errors"].includes(options.command) && (!options.username || !options.password)) {
+    throw new Error("BACKTRACE_USERNAME and BACKTRACE_PASSWORD are required");
+  }
+  if (!Number.isInteger(options.limit) || options.limit <= 0) {
+    throw new Error("--limit must be a positive integer");
+  }
+  if (!Number.isInteger(options.offset) || options.offset < 0) {
+    throw new Error("--offset must be a non-negative integer");
+  }
+  if (!Number.isInteger(options.retries) || options.retries < 0) {
+    throw new Error("--retries must be a non-negative integer; use 0 for infinite retry");
+  }
+  if (!Number.isInteger(options.downloadConcurrency) || options.downloadConcurrency <= 0) {
+    throw new Error("--download-concurrency must be a positive integer");
+  }
+  if (options.select.length === 0) {
+    throw new Error("--select must contain at least one field");
+  }
+  return options;
+}
+
+// 把旧版 Node 入口传入的 argv 解析为已校验的运行时选项。
+function parseArgs(argv) {
+  const range = nowRange();
+  const batchName = formatBatchName(new Date());
+  // 这里先填满默认值，后续只覆盖用户显式传入的字段。
+  const options = {
+    command: "",
+    queryUrl: normalizeBacktraceQueryUrl(DEFAULT_QUERY_URL),
+    workdir: DEFAULT_WORKDIR,
+    objectId: "",
+    fingerprint: "",
+    from: range.from,
+    to: range.to,
+    limit: DEFAULT_LIMIT,
+    offset: 0,
+    select: [...DEFAULT_SELECT],
+    proxy: DEFAULT_PROXY,
+    retries: DEFAULT_RETRIES,
+    downloadConcurrency: DEFAULT_DOWNLOAD_CONCURRENCY,
+    batchName,
+    storageDir: path.resolve(DEFAULT_STORAGE_DIR),
+    reportDir: path.resolve(DEFAULT_STORAGE_DIR),
+    logsDir: path.resolve(DEFAULT_STORAGE_DIR),
+    username: process.env.BACKTRACE_USERNAME || "",
+    password: process.env.BACKTRACE_PASSWORD || "",
+  };
+
+  let index = 0;
+  if (argv[0] && !argv[0].startsWith("-")) {
+    // 第一个非 flag 参数视为主命令。
+    options.command = argv[0];
+    index = 1;
+  }
+
+  // 按顺序解析参数，因为这里采用的是简单的成对参数约定。
+  for (; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--query-url") {
+      options.queryUrl = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--workdir") {
+      options.workdir = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--object-id") {
+      options.objectId = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--fingerprint") {
+      options.fingerprint = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--from") {
+      options.from = argv[index + 1] || options.from;
+      index += 1;
+      continue;
+    }
+    if (arg === "--to") {
+      options.to = argv[index + 1] || options.to;
+      index += 1;
+      continue;
+    }
+    if (arg === "--limit") {
+      options.limit = Number(argv[index + 1] || String(DEFAULT_LIMIT));
+      index += 1;
+      continue;
+    }
+    if (arg === "--offset") {
+      options.offset = Number(argv[index + 1] || "0");
+      index += 1;
+      continue;
+    }
+    if (arg === "--select") {
+      options.select = (argv[index + 1] || DEFAULT_SELECT.join(","))
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+      index += 1;
+      continue;
+    }
+    if (arg === "--proxy") {
+      options.proxy = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--retries") {
+      options.retries = Number(argv[index + 1] || String(DEFAULT_RETRIES));
+      index += 1;
+      continue;
+    }
+    if (arg === "--download-concurrency") {
+      options.downloadConcurrency = Number(argv[index + 1] || String(DEFAULT_DOWNLOAD_CONCURRENCY));
+      index += 1;
+      continue;
+    }
+    if (arg === "--storage-dir" || arg === "--report-dir" || arg === "--logs-dir") {
+      options.storageDir = path.resolve(argv[index + 1] || DEFAULT_STORAGE_DIR);
+      options.reportDir = options.storageDir;
+      options.logsDir = options.storageDir;
+      index += 1;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+  }
+
+  options.queryUrl = normalizeBacktraceQueryUrl(options.queryUrl || DEFAULT_QUERY_URL);
+  options.proxy = String(options.proxy || DEFAULT_PROXY || "").trim();
+
+  return validateOptions(options);
+}
+
+// 给直接调用库的场景构造选项，跳过原始 argv 解析。
+function createOptions(overrides = {}) {
+  const range = nowRange();
+  const batchName = overrides.batchName || formatBatchName(new Date());
+  // 支持调用方直接传数组，也支持传逗号分隔字符串。
+  const selectValue = Array.isArray(overrides.select)
+    ? overrides.select
+    : String(overrides.select || DEFAULT_SELECT.join(","))
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+
+  const options = {
+    command: overrides.command || "",
+    queryUrl: normalizeBacktraceQueryUrl(overrides.queryUrl || DEFAULT_QUERY_URL),
+    workdir: overrides.workdir || DEFAULT_WORKDIR,
+    objectId: overrides.objectId ? String(overrides.objectId) : "",
+    fingerprint: overrides.fingerprint ? String(overrides.fingerprint) : "",
+    from: String(overrides.from || range.from),
+    to: String(overrides.to || range.to),
+    limit: normalizeOptionalInteger(overrides.limit, DEFAULT_LIMIT),
+    offset: normalizeOptionalInteger(overrides.offset, 0),
+    select: selectValue.length > 0 ? selectValue : [...DEFAULT_SELECT],
+    proxy: String(overrides.proxy || DEFAULT_PROXY || "").trim(),
+    retries: normalizeOptionalInteger(overrides.retries, DEFAULT_RETRIES),
+    downloadConcurrency: normalizeOptionalInteger(overrides.downloadConcurrency, DEFAULT_DOWNLOAD_CONCURRENCY),
+    batchName,
+    storageDir: path.resolve(overrides.storageDir || overrides.reportDir || overrides.logsDir || DEFAULT_STORAGE_DIR),
+    reportDir: path.resolve(overrides.storageDir || overrides.reportDir || overrides.logsDir || DEFAULT_STORAGE_DIR),
+    logsDir: path.resolve(overrides.storageDir || overrides.reportDir || overrides.logsDir || DEFAULT_STORAGE_DIR),
+    username: overrides.username || process.env.BACKTRACE_USERNAME || "",
+    password: overrides.password || process.env.BACKTRACE_PASSWORD || "",
+  };
+
+  return validateOptions(options);
+}
+
+module.exports = {
+  SUPPORTED_COMMANDS,
+  printUsage,
+  parseArgs,
+  createOptions,
+  validateOptions,
+};