backtrace-console 0.0.1

package/lib/cli/args.js

@@ -0,0 +1,177 @@
+// 解析 bin/backtrace-cli.js 使用的轻量命令行语法，
+// 把 argv 数组转换成后续流程需要的标准化选项对象。
+function printCliUsage() {
+  console.log([
+    "Usage:",
+    "  backtrace <command> [options]",
+    "",
+    "Commands:",
+    "  list",
+    "  fingerprint",
+    "  collect",
+    "  summarize-errors",
+    "  fix-plan",
+    "  apply-fix",
+    "",
+    "Shared options:",
+    "  --fingerprint <value[,value2,...]>",
+    "  --from <unixTs>                 default: 1",
+    "  --to <unixTs>                   default: now",
+    "  --query-url <url>",
+    "  --proxy <url>",
+    "  --workdir <dir>",
+    "  --storage-dir <dir>",
+    "  --download-concurrency <n>",
+    "",
+    "Fix-plan options:",
+    "  --fingerprint <value>        required for backtrace fix-plan",
+    "  --report-path <path>        relative path under fingerprints/",
+    "  --repair-plan-path <path>   relative path of existing repair plan file",
+    "  --repair-version <value>",
+    "  --plan-file <path>          load plan text from file",
+    "  --plan-text <text>          pass plan text directly",
+    "",
+    "Examples:",
+    "  backtrace list",
+    "  backtrace fingerprint",
+    "  backtrace fingerprint db221f7a4f76...",
+    "  backtrace collect --fingerprint db221f7",
+    "  backtrace summarize-errors --fingerprint db221f7a4f76...",
+    "  backtrace fix-plan --fingerprint db221f7a4f76...",
+    "  backtrace apply-fix --fingerprint db221f7a4f76...",
+  ].join("\n"));
+}
+
+// 保持显式解析，这样每个支持的参数都只映射到一个确定字段，
+// 调用方也能明确区分“显示帮助”和“执行命令”两种模式。
+function parseCliArgs(argv) {
+  const args = Array.from(argv || []);
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    return { help: true };
+  }
+
+  const command = args[0];
+  let index = 1;
+
+  const options = {
+    command,
+    fingerprint: "",
+    objectId: "",
+    from: "",
+    to: "",
+    queryUrl: "",
+    proxy: "",
+    workdir: "",
+    storageDir: "",
+    downloadConcurrency: "",
+    limit: "",
+    offset: "",
+    select: "",
+    reportPath: "",
+    repairPlanPath: "",
+    repairVersion: "",
+    planFile: "",
+    planText: "",
+  };
+
+  // 按顺序解析参数，因为这里只支持简单的
+  // "--name value" 形式，以及一个可选的 fix-plan 子命令。
+  for (; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("-") && command === "fingerprint" && !options.fingerprint) {
+      options.fingerprint = arg;
+      continue;
+    }
+    if (arg === "--fingerprint") {
+      options.fingerprint = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--object-id") {
+      options.objectId = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--from") {
+      options.from = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--to") {
+      options.to = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--query-url") {
+      options.queryUrl = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--proxy") {
+      options.proxy = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--workdir") {
+      options.workdir = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--storage-dir") {
+      options.storageDir = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--download-concurrency") {
+      options.downloadConcurrency = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--limit") {
+      options.limit = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--offset") {
+      options.offset = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--select") {
+      options.select = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--report-path") {
+      options.reportPath = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--repair-plan-path") {
+      options.repairPlanPath = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--repair-version") {
+      options.repairVersion = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--plan-file") {
+      options.planFile = args[index + 1] || "";
+      index += 1;
+      continue;
+    }
+    if (arg === "--plan-text") {
+      options.planText = args[index + 1] || "";
+      index += 1;
+    }
+  }
+
+  return { help: false, options };
+}
+
+module.exports = {
+  printCliUsage,
+  parseCliArgs,
+};

package/lib/cli/run.js

@@ -0,0 +1,191 @@
+const fs = require("node:fs/promises");
+const { createOptions, runBacktraceCommand, printList } = require("../BacktraceCodexTool");
+const { applyFixFromFingerprint, generateRepairPlanFromFingerprint } = require("../backtrace/repair-fingerprint");
+
+// 把 CLI 原始字符串参数转换成底层 Backtrace 工具共用的标准选项结构。
+function buildBacktraceOverrides(rawOptions, command) {
+  const overrides = { command };
+  // 这里只复制用户显式传入的字段，避免把空字符串覆盖默认值。
+  if (rawOptions.fingerprint) {
+    overrides.fingerprint = rawOptions.fingerprint;
+  }
+  if (rawOptions.objectId) {
+    overrides.objectId = rawOptions.objectId;
+  }
+  if (rawOptions.from) {
+    overrides.from = rawOptions.from;
+  }
+  if (rawOptions.to) {
+    overrides.to = rawOptions.to;
+  }
+  if (rawOptions.queryUrl) {
+    overrides.queryUrl = rawOptions.queryUrl;
+  }
+  if (rawOptions.proxy) {
+    overrides.proxy = rawOptions.proxy;
+  }
+  if (rawOptions.workdir) {
+    overrides.workdir = rawOptions.workdir;
+  }
+  if (rawOptions.storageDir) {
+    overrides.storageDir = rawOptions.storageDir;
+  }
+  if (rawOptions.downloadConcurrency) {
+    overrides.downloadConcurrency = Number(rawOptions.downloadConcurrency);
+  }
+  if (rawOptions.limit) {
+    overrides.limit = Number(rawOptions.limit);
+  }
+  if (rawOptions.offset) {
+    overrides.offset = Number(rawOptions.offset);
+  }
+  if (rawOptions.select) {
+    overrides.select = rawOptions.select;
+  }
+  return createOptions(overrides);
+}
+
+// CLI 默认输出结构化 JSON，便于管道处理和人工查看。
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function formatUnixTimestamp(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return String(value || "");
+  }
+  return `${numeric} (${new Date(numeric * 1000).toISOString()})`;
+}
+
+function formatObjectTimestamp(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return String(value || "");
+  }
+  const date = new Date(numeric * 1000);
+  const year = String(date.getFullYear());
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hour = String(date.getHours()).padStart(2, "0");
+  const minute = String(date.getMinutes()).padStart(2, "0");
+  const second = String(date.getSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hour}:${minute}:${second} (${numeric})`;
+}
+
+function truncateLine(value, maxLength = 200) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength)}...`;
+}
+
+function printFingerprintDetail(result) {
+  console.log(`Fingerprint: ${result.fingerprint}`);
+  console.log(`First Seen: ${formatUnixTimestamp(result.firstSeen)}`);
+  console.log(`Issue State: ${result.issueState || ""}`);
+  console.log(`Classifiers: ${result.classifiers || ""}`);
+  console.log(`Object Count: ${result.objectCount}`);
+  console.log(`Query Total Rows: ${result.querySummary?.totalRows ?? result.objectCount}`);
+  console.log(`Fetched Objects: ${result.querySummary?.fetchedRows ?? result.objectCount}`);
+  console.log(`Page Limit: ${result.querySummary?.pageLimit ?? ""}`);
+  console.log(`Error Message: ${truncateLine(result.errorMessage, 240)}`);
+  console.log("");
+  console.log("Objects:");
+
+  if (!Array.isArray(result.objects) || result.objects.length === 0) {
+    console.log("No objects found.");
+    return;
+  }
+
+  result.objects.forEach((item, index) => {
+    console.log(`${index + 1}. ${item.objectIdHex}  ${formatObjectTimestamp(item.timestamp)}`);
+  });
+}
+
+function printLocalFingerprintList(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    console.log("No local fingerprints found.");
+    return;
+  }
+
+  items.forEach((item, index) => {
+    console.log(`${index + 1}. ${item.fingerprint}`);
+    console.log(`   State: ${item.issueState || ""}`);
+    console.log(`   Error: ${truncateLine(item.errorMessage, 200)}`);
+  });
+}
+
+// 根据解析后的命令分发到对应的 Backtrace 或修复流程。
+async function runCliCommand(rawOptions) {
+  if (rawOptions.command === "list") {
+    const options = buildBacktraceOverrides(rawOptions, "list");
+    const result = await runBacktraceCommand("list", options);
+    printLocalFingerprintList(result.items);
+    return;
+  }
+
+  if (rawOptions.command === "fingerprint") {
+    // fingerprint 只查远端并打印指纹列表，不涉及本地分析和报告生成。
+    const options = buildBacktraceOverrides(rawOptions, "fingerprint");
+    const result = await runBacktraceCommand("fingerprint", options);
+    if (result.mode === "detail") {
+      printFingerprintDetail(result);
+      return;
+    }
+    printList(result.items, {
+      from: options.from,
+      to: options.to,
+      totalRows: result.querySummary.totalRows,
+      totalListed: result.querySummary.fetchedRows,
+      objectCount: result.querySummary.objectCount,
+      pageLimit: result.querySummary.pageLimit,
+    });
+    return;
+  }
+
+  if (rawOptions.command === "collect") {
+    // collect 只做下载，不生成分析报告。
+    const options = buildBacktraceOverrides(rawOptions, "collect-all");
+    const result = await runBacktraceCommand("collect-all", options);
+    printJson({
+      command: "collect",
+      fingerprint: options.fingerprint || "",
+      downloadedCount: result.downloadedItems.length,
+      storageDir: options.storageDir,
+    });
+    return;
+  }
+
+  if (rawOptions.command === "summarize-errors") {
+    const options = buildBacktraceOverrides(rawOptions, "summarize-fingerprint-errors");
+    const result = await runBacktraceCommand("summarize-fingerprint-errors", options);
+    printJson(result);
+    return;
+  }
+
+  if (rawOptions.command === "fix-plan") {
+    if (!rawOptions.fingerprint) {
+      throw new Error("--fingerprint is required for fix-plan");
+    }
+    const result = await generateRepairPlanFromFingerprint({ fingerprint: rawOptions.fingerprint }, rawOptions);
+    printJson(result);
+    return;
+  }
+
+  if (rawOptions.command === "apply-fix") {
+    if (!rawOptions.fingerprint) {
+      throw new Error("--fingerprint is required for apply-fix");
+    }
+    const result = await applyFixFromFingerprint({ fingerprint: rawOptions.fingerprint }, rawOptions);
+    printJson(result);
+    return;
+  }
+
+  throw new Error("Unsupported command. Use --help to see available commands.");
+}
+
+module.exports = {
+  runCliCommand,
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "backtrace-console",
+  "version": "0.0.1",
+  "description": "CLI for querying Backtrace fingerprints, collecting artifacts, and generating repair plans.",
+  "private": false,
+  "files": [
+    "app.js",
+    "bin",
+    "lib",
+    "public",
+    "routes"
+  ],
+  "bin": {
+    "backtrace": "bin/backtrace-cli.js"
+  },
+  "scripts": {
+    "start": "node ./bin/www",
+    "backtrace": "node ./bin/backtrace-cli.js"
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "^0.118.0",
+    "cookie-parser": "~1.4.4",
+    "debug": "~2.6.9",
+    "dotenv": "^17.4.1",
+    "express": "~4.16.1",
+    "morgan": "~1.9.1",
+    "undici": "^7.24.8"
+  }
+}